@qe-libs/rena-wasm 0.1.8 → 0.1.9

package/README.md

@@ -111,6 +111,67 @@ everyone's windows.
 
 ---
 
+## Infinite Windows
+
+`window: Infinity` (= R's `window.size.back = Inf`) connects each line to
+every earlier line in its conversation. It also works as a window in a
+context tensor.
+
+```js
+const model = ena.fit(rows, { codes, units, conversations, window: Infinity });
+```
+
+---
+
+## Normalization and Centring
+
+`sphereNorm` (default `true`, = R's `norm.by = fun_sphere_norm`) scales each
+unit's network to length 1. With `false` (= `fun_skip_sphere_norm`) every
+network is scaled by the longest network's length instead, keeping relative
+magnitudes; for ordered (ONA) models this is
+`ona::model(normalize = skip_sphere_norm)`. `centerAlignToOrigin` (default
+`true`, = `ena.make.set`'s `center.align.to.origin`) leaves zero-network units
+out of the centring mean and at the origin; with `false` the mean is taken
+over, and subtracted from, every unit. It applies to unordered models only —
+ordered models always centre as `ona::model()` does. Both work in `fit()` and
+`pria()`.
+
+```js
+const model = ena.fit(rows, { codes, units, conversations, window: 4,
+                              sphereNorm: false, centerAlignToOrigin: false });
+```
+
+---
+
+## Projecting Into Another Model (Custom Rotation)
+
+`rotationSet` (= R's `rotation.set` in `ena.make.set()`) projects a model into
+another model's space instead of rotating it: the units are centred on the
+rotation set's `centerVec` and projected with its `rotationMatrix`, and the
+nodes are the rotation set's. Pass `codes` (the rotation set's code order) to
+have it reordered to the model's codes; a rotation set built from other codes
+is rejected. Centroids use the pinned nodes, so goodness of fit is measured
+against the nodes shown. Ordered models keep their own centring, as
+rENA.api's ordered pipeline does.
+
+```js
+const source = ena.fit(rowsA, { codes, units, conversations, window: 4 });
+const model  = ena.fit(rowsB, { codes, units, conversations, window: 4,
+  rotationSet: {
+    rotationMatrix: source.rotationMatrix, rotationCols: source.dims,
+    nodes:          source.rotation.nodes,
+    centerVec:      source.rotation.centerVec,
+    codes,
+  },
+});
+```
+
+`rotationMatrix` and `nodes` may also be arrays of rows (one per connection
+and per code), as R stores them. `pria()` ignores `rotationSet`: it cannot
+rotate the reduced models.
+
+---
+
 ## Reduced-Code Search (PRIA)
 
 `pria()` finds the largest set of codes (up to `removeNum`, never leaving
@@ -195,6 +256,40 @@ data[a + nA*b + nA*nB*1]  →  window for factor combination (a, b)
 | `dimsReceiver` | These axes use the *response* row's factor values (overrides ground) |
 | `dimsMode` | These axes use a shared mode value |
 
+### Time-based windows
+
+Set `timesCol` to measure windows in time instead of lines, and `timeUnit`
+('secs' (default), 'mins', 'hours', 'days', 'weeks') to give the tensor's
+windows in that unit. Numeric time columns are used as-is; otherwise each
+value is parsed as elapsed time (`MM:SS`, `HH:MM:SS`) or a date-time, in
+seconds, as rENA.api's `parse_date` does. `timesEndCol` uses each row's end
+time instead: a numeric column is a duration added to the start, anything
+else is the end timestamp.
+
+```js
+const tensor = { ...modalityTensor, timesCol: 'Timestamp', timeUnit: 'mins' };
+```
+
+### Flexible horizons
+
+`horizons` gives every unit its own horizon of observation (= tma
+`contexts()` with HOO rules, as rENA.api builds them for flexible horizons).
+`by` is the discriminator column and `rules` maps each of its values to the
+columns that define that value's horizon: a row is in unit U's horizon when
+each of those columns holds a value U has. Each horizon is split on the rules'
+columns — not on the discriminator, which only picks the rule — and windows
+run within each piece. Rows whose discriminator value has no rule are left
+out.
+
+```js
+const model = ena.fit(rows, {
+  codes, units, conversations: ['Modality'], tensor,
+  horizons: { by: 'Modality', rules: { chat: ['GroupName'], log: ['UserName'] } },
+});
+```
+
+`horizons` works in `fit()`, `accumulate()`, `tuneWindowSize()` and `pria()`.
+
 ### `defaultTensor` helper
 
 Express simple windowed accumulation as a tensor (IS_DEFAULT path):
@@ -233,4 +328,9 @@ npm test
 ```
 
 Tests cover the simple windowed pipeline (`test/ena.test.js`) and the
-context-tensor path (`test/tensor.test.js`).
+context-tensor path (`test/tensor.test.js`), and check against R: infinite and
+time-based windows, flexible horizons and custom rotations
+(`test/windows-horizons-rotation.test.js`), the normalization and centring
+options against `ena.make.set()` (`test/norm-center.test.js`), and ordered
+models with and without sphere normalization against `ona::model()`
+(`test/ona-model.test.js`, `test/ona-sphere-norm.test.js`).

package/package.json

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

package/src/index.js

@@ -43,9 +43,9 @@
 import loadLibQE from '@qe-libs/libqe-wasm';
 import { parseData } from './data.js';
 import {
-    sphereNorm, center,
+    sphereNorm, scaleNetworks, center,
     rotateSVD, rotateMeans, rotateGeneralized,
-    project, nodePositions, spaceDistCorr,
+    project, nodePositions, spaceDistCorr, matmul,
 } from './pipeline.js';
 import { accumulateTensor, defaultTensor } from './tensor.js';
 
@@ -272,22 +272,125 @@ function applyCodeMask(networks, codeMask, nCodes, nUnits, nConnections, ordered
     }
 }
 
+// ── custom rotation (= R's rotation.set) ─────────────────────────────────────
+
+// Rows of a matrix given as an array of row arrays, or as flat row-major data
+// with `cols` columns.
+function matrixRows(m, cols) {
+    if (m == null) return null;
+    if (Array.isArray(m) && (m.length === 0 || Array.isArray(m[0]) || ArrayBuffer.isView(m[0]))) {
+        return m.map(r => Array.from(r, Number));
+    }
+    const flat = Array.from(m, Number);
+    if (!cols) throw new Error('a flat rotation matrix needs its column count');
+    const rows = [];
+    for (let i = 0; i < flat.length; i += cols) rows.push(flat.slice(i, i + cols));
+    return rows;
+}
+
+/**
+ * Validate a supplied rotation set (= R's ena.rotation.set, e.g. another
+ * model's rotation) against this model's codes, and reorder it to this
+ * model's code order. Throws when it cannot rotate this model.
+ *
+ * @param {object}   rs  { rotationMatrix, nodes, centerVec, codes?,
+ *                         rotationCols?, eigenvalues?, columnNames? }
+ *                       rotationMatrix: nConnections rows (array of rows, or
+ *                       flat row-major with rotationCols); nodes: one row per
+ *                       code; centerVec: one entry per connection.
+ * @returns {{ rotation: Float64Array, rotRows: number, rotCols: number,
+ *             nodes: number[][], centerVec: Float64Array,
+ *             eigenvalues: number[]|null, columnNames: string[] }}
+ */
+function resolveRotationSet(rs, codes, nConnections, ordered) {
+    const rot = matrixRows(rs.rotationMatrix, rs.rotationCols);
+    if (!rot || rot.length !== nConnections) {
+        throw new Error(
+            `rotationSet has ${rot ? rot.length : 0} connections but this model has ` +
+            `${nConnections} -- it was built from different codes` +
+            (ordered ? ' or is not an ordered model' : ' or is an ordered model')
+        );
+    }
+    const rotCols = rot[0].length;
+    const nodes   = matrixRows(rs.nodes, rotCols);
+    const center  = rs.centerVec ? Array.from(rs.centerVec, Number) : null;
+    if (!nodes || nodes.length !== codes.length) {
+        throw new Error('rotationSet.nodes must have one row per code');
+    }
+    if (!ordered && (!center || center.length !== nConnections)) {
+        throw new Error('rotationSet.centerVec must have one entry per connection');
+    }
+
+    // Map this model's codes/connections onto the rotation set's order.
+    let codeIdx = codes.map((_, i) => i);
+    let connIdx = Array.from({ length: nConnections }, (_, k) => k);
+    if (rs.codes) {
+        const src = rs.codes.map(String);
+        codeIdx = codes.map(c => src.indexOf(String(c)));
+        if (src.length !== codes.length || codeIdx.some(i => i < 0)) {
+            throw new Error('rotationSet.codes do not match this model\'s codes');
+        }
+        const srcKey = new Map(buildAdjacencyKey(src, ordered).map(([a, b], k) => [a + '\u0000' + b, k]));
+        connIdx = buildAdjacencyKey(codes, ordered).map(([a, b]) => {
+            const k = srcKey.get(a + '\u0000' + b) ?? (ordered ? undefined : srcKey.get(b + '\u0000' + a));
+            if (k === undefined) throw new Error(`rotationSet has no connection '${a} & ${b}'`);
+            return k;
+        });
+    }
+
+    const rotation = new Float64Array(nConnections * rotCols);
+    connIdx.forEach((k, r) => rotation.set(rot[k], r * rotCols));
+    return {
+        rotation, rotRows: nConnections, rotCols,
+        nodes:       codeIdx.map(i => nodes[i]),
+        centerVec:   center ? Float64Array.from(connIdx, k => center[k]) : null,
+        eigenvalues: rs.eigenvalues ? Array.from(rs.eigenvalues, Number) : null,
+        columnNames: (rs.columnNames && rs.columnNames.length >= rotCols)
+            ? rs.columnNames.slice(0, rotCols).map(String)
+            : Array.from({ length: rotCols }, (_, d) => `Dim${d + 1}`),
+    };
+}
+
 // ── shared pipeline (post-accumulation) ──────────────────────────────────────
 
+// norm: { sphereNorm = true, centerAlignToOrigin = true } (= R's norm.by /
+// model(normalize =) and ena.make.set's center.align.to.origin). sphereNorm
+// applies to every model; centerAlignToOrigin to unordered models only --
+// ordered (ONA) models always centre as ona::model() does.
 function runPipeline(qe, rawNetworks, nUnits, nConnections, codes, unitLabels,
                      metaData, rotMethod, groupA, groupB, dims, gParams,
-                     rowConnectionCounts = null, ordered = false) {
+                     rowConnectionCounts = null, ordered = false, rotationSet = null,
+                     norm = {}) {
     const connectionNames = connectionNamesFor(qe, codes, ordered);
+    const useSphereNorm = norm.sphereNorm !== false;
+    const alignToOrigin = ordered || norm.centerAlignToOrigin !== false;
 
-    // Sphere norm → lineWeights (= R's set$line.weights)
-    const lineWeights = sphereNorm(qe, rawNetworks, nUnits, nConnections);
+    // Sphere norm → lineWeights (= R's set$line.weights). Without it, every
+    // network is scaled by the largest network's length (fun_skip_sphere_norm).
+    const lineWeights = useSphereNorm
+        ? sphereNorm(qe, rawNetworks, nUnits, nConnections)
+        : scaleNetworks(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.
+    // Zero-network units are left out of the mean and stay at the origin,
+    // unless centerAlignToOrigin is false (mean over, and shift of, every
+    // unit). 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, ordered);
+        center(qe, lineWeights, nUnits, nConnections, ordered, !alignToOrigin);
+
+    // Custom rotation (= R's rotation.set): project into another model's
+    // space -- its rotation matrix and node positions, and, for unordered
+    // models, its centering vector (rENA's center.projection). Ordered models
+    // keep their own centering, as rENA.api's ordered pipeline does.
+    if (rotationSet) {
+        return runCustomRotation(qe, rawNetworks, lineWeights, pointsForProjection,
+                                 centerVec, nUnits, nConnections, codes, unitLabels,
+                                 metaData, dims, rowConnectionCounts, ordered,
+                                 resolveRotationSet(rotationSet, codes, nConnections, ordered),
+                                 alignToOrigin);
+    }
 
     // Rotate
     let rot;
@@ -378,6 +481,75 @@ function runPipeline(qe, rawNetworks, nUnits, nConnections, codes, unitLabels,
     });
 }
 
+function runCustomRotation(qe, rawNetworks, lineWeights, ownCentered, ownCenterVec,
+                           nUnits, nConnections, codes, unitLabels, metaData, dims,
+                           rowConnectionCounts, ordered, rs, alignToOrigin = true) {
+    let pointsForProjection = ownCentered;
+    let centerVec = ownCenterVec;
+    if (!ordered) {
+        // rENA center.projection: subtract the rotation set's center vector
+        // (zero-network units stay at the origin unless centerAlignToOrigin
+        // is false, as center() leaves them).
+        centerVec = rs.centerVec;
+        pointsForProjection = new Float64Array(lineWeights.length);
+        for (let u = 0; u < nUnits; u++) {
+            let rowSum = 0;
+            for (let c = 0; c < nConnections; c++) rowSum += Math.abs(lineWeights[u * nConnections + c]);
+            if (rowSum === 0 && alignToOrigin) continue;
+            for (let c = 0; c < nConnections; c++) {
+                pointsForProjection[u * nConnections + c] = lineWeights[u * nConnections + c] - centerVec[c];
+            }
+        }
+    }
+
+    dims = Math.min(dims, rs.rotCols);
+    const rotationMatrix = new Float64Array(rs.rotRows * dims);
+    for (let r = 0; r < rs.rotRows; r++)
+        for (let d = 0; d < dims; d++)
+            rotationMatrix[r * dims + d] = rs.rotation[r * rs.rotCols + d];
+
+    const points = project(pointsForProjection, nUnits, nConnections,
+                           rs.rotation, rs.rotRows, rs.rotCols, dims);
+
+    // Nodes are the rotation set's (R keeps rotation.set$nodes). Centroids:
+    // ordered models keep optimize()'s centroids, as rENA.api does; unordered
+    // ones place each unit at its normalised node-weight average of the
+    // pinned nodes -- libqe's node_positions weights × the rotation set's
+    // nodes -- so goodness of fit is measured against the nodes shown.
+    const nodes = new Float64Array(codes.length * dims);
+    rs.nodes.forEach((row, c) => { for (let d = 0; d < dims; d++) nodes[c * dims + d] = Number(row[d]) || 0; });
+    let centroids;
+    if (ordered) {
+        centroids = nodePositions(qe, lineWeights, nUnits, nConnections, points, dims, true).centroids;
+    } else {
+        const w = qe.node_positions(lineWeights, nUnits, nConnections, points, nUnits, dims, dims).weights;
+        centroids = matmul(Float64Array.from(w.data), nUnits, w.cols, nodes, dims);
+    }
+
+    return new ENAModel({
+        connectionCounts:     rawNetworks,
+        rowConnectionCounts,
+        lineWeights,
+        points,
+        rotationMatrix,
+        metaData,
+        connectionNames:      connectionNamesFor(qe, codes, ordered),
+        nUnits,
+        nConnections,
+        dims,
+        centroids,
+        variance:             computeVariance(points, nUnits, dims),
+        unitLabels,
+        pointsForProjection,
+        nodes,
+        columnNames:          rs.columnNames.slice(0, dims),
+        eigenvalues:          rs.eigenvalues,
+        centerVec,
+        codes,
+        adjacencyKey:         buildAdjacencyKey(codes, ordered),
+    });
+}
+
 // ── main factory ─────────────────────────────────────────────────────────────
 
 /**
@@ -409,6 +581,23 @@ export default async function loadENA() {
          * @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
+         * @param {object}   [opts.horizons]       - Flexible horizons { by, rules: { value: [cols] } }
+         *                                           (see tensor.js buildHorizonContexts); replaces
+         *                                           the conversations as the windowing contexts
+         * @param {object}   [opts.rotationSet]    - Project into another model's space (= R's
+         *                                           rotation.set): { rotationMatrix, nodes,
+         *                                           centerVec, codes?, rotationCols?,
+         *                                           eigenvalues?, columnNames? }; overrides
+         *                                           opts.rotation
+         * @param {boolean}  [opts.sphereNorm=true] - Sphere-normalize each network (= R's
+         *                                           norm.by = fun_sphere_norm); false scales
+         *                                           all networks by the longest one
+         *                                           (fun_skip_sphere_norm; for ordered models,
+         *                                           ona::model(normalize = skip_sphere_norm)).
+         * @param {boolean}  [opts.centerAlignToOrigin=true] - Keep zero-network units at the
+         *                                           origin and out of the centring mean (= R's
+         *                                           center.align.to.origin); false centres on
+         *                                           every unit. Unordered only.
          *
          * @returns {ENAModel}
          */
@@ -429,6 +618,10 @@ export default async function loadENA() {
                 codeMask,
                 weightModel,
                 unitsUsed,
+                horizons,
+                rotationSet,
+                sphereNorm:          useSphereNorm       = true,
+                centerAlignToOrigin                       = true,
             } = opts;
 
             if (!codes?.length)         throw new Error('opts.codes is required');
@@ -452,7 +645,7 @@ export default async function loadENA() {
             const { networks: rawNetworks, rowConnectionCounts } = accumulateTensor(
                 qe, rows, codeMatrix, nRows, nCodes, nUnits,
                 unitOf, convoGroups, tensorDef ?? defaultTensor(windowSize),
-                ordered, binary, weight
+                ordered, binary, weight, horizons
             );
             const nConnections = ordered ? nCodes * nCodes : qe.choose_two(nCodes);
 
@@ -460,7 +653,8 @@ export default async function loadENA() {
 
             return runPipeline(qe, rawNetworks, nUnits, nConnections, codes,
                                unitLabels, metaData, rotMethod, groupA, groupB,
-                               dims, gParams, rowConnectionCounts, ordered);
+                               dims, gParams, rowConnectionCounts, ordered,
+                               rotationSet, { sphereNorm: useSphereNorm, centerAlignToOrigin });
         },
 
         /**
@@ -468,7 +662,8 @@ export default async function loadENA() {
          * Returns raw (un-normalised) network vectors.
          *
          * @param {Object[]} rows
-         * @param {object}   opts  - codes, units, conversations, window, binary, ordered, tensor, weightModel
+         * @param {object}   opts  - codes, units, conversations, window, binary, ordered, tensor,
+         *                           weightModel, codeMask, unitsUsed, horizons
          * @returns {{
          *   connectionCounts: Float64Array,
          *   rowConnectionCounts: Float64Array | null,
@@ -490,6 +685,7 @@ export default async function loadENA() {
                 codeMask,
                 weightModel,
                 unitsUsed,
+                horizons,
             } = opts;
 
             const { codeMatrix, nRows, nCodes, nUnits, unitLabels,
@@ -499,7 +695,7 @@ export default async function loadENA() {
             const { networks, rowConnectionCounts } = accumulateTensor(
                 qe, rows, codeMatrix, nRows, nCodes, nUnits,
                 unitOf, convoGroups, tensorDef ?? defaultTensor(windowSize),
-                ordered, binary, weightModelName(weightModel)
+                ordered, binary, weightModelName(weightModel), horizons
             );
             const nConnections = ordered ? nCodes * nCodes : qe.choose_two(nCodes);
 
@@ -513,7 +709,7 @@ export default async function loadENA() {
                 // (= R's ENAAccumulation$`_function.call`).
                 _call: { rows, codes, units, conversations,
                          window: windowSize, binary, ordered, tensor: tensorDef,
-                         weightModel, unitsUsed },
+                         weightModel, unitsUsed, horizons },
             };
         },
 
@@ -551,7 +747,8 @@ export default async function loadENA() {
                 'maxSize must be greater than minSize to compare windows.'
             );
 
-            const { rows, codes, units, conversations, binary, ordered, weightModel, unitsUsed } = call;
+            const { rows, codes, units, conversations, binary, ordered, weightModel, unitsUsed,
+                    horizons } = call;
 
             // Parse once; only the window size changes between iterations.
             const { codeMatrix, nRows, nCodes, nUnits, unitLabels,
@@ -566,7 +763,7 @@ export default async function loadENA() {
                 const { networks: raw } = accumulateTensor(
                     qe, rows, codeMatrix, nRows, nCodes, nUnits,
                     unitOf, convoGroups, defaultTensor(w), ordered, binary,
-                    weightModelName(weightModel)
+                    weightModelName(weightModel), horizons
                 );
                 const model = runPipeline(
                     qe, raw, nUnits, nConnections, codes,
@@ -594,7 +791,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, unitsUsed,
+                weightModel, unitsUsed, horizons,
             });
         },
 
@@ -727,7 +924,11 @@ export default async function loadENA() {
          * @param {object}   opts  - fit() options (codes, units, conversations,
          *                           window, binary, ordered, tensor, weightModel,
          *                           codeMask, rotation, groupA, groupB, gParams,
-         *                           unitsUsed)
+         *                           unitsUsed, horizons, sphereNorm,
+         *                           centerAlignToOrigin). A rotationSet is
+         *                           ignored: it cannot rotate the reduced
+         *                           models, so every candidate is scored in
+         *                           opts.rotation.
          *                           plus removeNum (default 3) and threshold
          *                           (default 0.95). `dims` is ignored: scoring
          *                           uses dims 1:2 and the variance uses all dims.
@@ -740,7 +941,8 @@ 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, unitsUsed,
+                removeNum = 3, threshold = 0.95, unitsUsed, horizons,
+                sphereNorm = true, centerAlignToOrigin = true,
             } = opts;
             if (!codes?.length)         throw new Error('opts.codes is required');
             if (!units?.length)         throw new Error('opts.units is required');
@@ -758,7 +960,7 @@ export default async function loadENA() {
             const { networks: raw } = accumulateTensor(
                 qe, rows, codeMatrix, nRows, nCodes, nUnits,
                 unitOf, convoGroups, tensorDef ?? defaultTensor(windowSize),
-                ordered, binary, weightModelName(weightModel)
+                ordered, binary, weightModelName(weightModel), horizons
             );
             const nConnections = ordered ? nCodes * nCodes : qe.choose_two(nCodes);
             applyCodeMask(raw, codeMask, nCodes, nUnits, nConnections, ordered);
@@ -794,7 +996,8 @@ export default async function loadENA() {
                 }
                 return runPipeline(qe, networks, nUnits, nConn, keptCodes,
                                    unitLabels, metaData, rotation, groupA, groupB,
-                                   nConn, gParams, null, ordered);
+                                   nConn, gParams, null, ordered, null,
+                                   { sphereNorm, centerAlignToOrigin });
             };
 
             const D = 2;  // score on the first 2 dims (R's get_pria_scores_2Ds)

package/src/pipeline.js

@@ -127,6 +127,16 @@ export function sphereNorm(qe, networks, nUnits, nConnections) {
     return new Float64Array(result.data);
 }
 
+/**
+ * Scale every network by the reciprocal of the largest row L2 norm, keeping
+ * relative magnitudes across units (= rENA's fun_skip_sphere_norm, used when
+ * sphere normalization is off).
+ */
+export function scaleNetworks(qe, networks, nUnits, nConnections) {
+    const result = qe.scale_networks(networks, nUnits, nConnections);
+    return new Float64Array(result.data);
+}
+
 // ── centering ─────────────────────────────────────────────────────────────────
 
 /**
@@ -137,17 +147,21 @@ export function sphereNorm(qe, networks, nUnits, nConnections) {
  *   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().
+ * @param {boolean} [includeZeroRows=false]  Take the mean over every row,
+ *   zero networks included, and shift every row by it: rENA's
+ *   ena.make.set(center.align.to.origin = FALSE). Overrides shiftZeroRows.
  * @returns {{ centered: Float64Array, centerVec: Float64Array }}
  *   centered  — mean-subtracted networks
  *   centerVec — the column means used for centering (= R's rotation$center.vec)
  */
-export function center(qe, networks, nUnits, nConnections, shiftZeroRows = false) {
-    // Identify non-zero rows
+export function center(qe, networks, nUnits, nConnections, shiftZeroRows = false,
+                       includeZeroRows = false) {
+    // Identify non-zero rows (every row when zero networks are included)
     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);
+        if (rowSum > 0 || includeZeroRows) active.push(u);
     }
 
     // Compute column means over active rows only (= R's rotation$center.vec)
@@ -164,7 +178,7 @@ export function center(qe, networks, nUnits, nConnections, shiftZeroRows = false
     const activeSet = new Set(active);
     const centered  = new Float64Array(networks.length);
     for (let u = 0; u < nUnits; u++) {
-        if (!shiftZeroRows && !activeSet.has(u)) continue;   // leave zero-network row as zero
+        if (!shiftZeroRows && !includeZeroRows && !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

@@ -36,9 +36,25 @@
  *
  *     // Optional column name for per-row timestamps.
  *     // Defaults to row index (0, 1, 2, ...) — equivalent to unit-step time.
+ *     // Numeric columns are used as-is; otherwise every value is parsed as
+ *     // elapsed time (MM:SS, HH:MM:SS) or a date-time, in seconds (parseTimes).
  *     timesCol: 'timestamp',
+ *
+ *     // Optional unit the windows in `data` are expressed in when timesCol is
+ *     // set: 'secs' (default) | 'mins' | 'hours' | 'days' | 'weeks'. Windows
+ *     // are converted to seconds before accumulation, as rENA.api does with
+ *     // mins_to_seconds() etc.
+ *     timeUnit: 'mins',
+ *
+ *     // Optional end-time column (rENA.api's timeend_column). A numeric column
+ *     // is a duration added to the start time; anything else is parsed as the
+ *     // row's end timestamp. Either way the row's time becomes its end time.
+ *     timesEndCol: 'duration',
  *   }
  *
+ * A window of Infinity (e.g. defaultTensor(Infinity), = rENA's
+ * window.size.back = Inf) includes every earlier line of the conversation.
+ *
  * Simple windowed accumulation (IS_DEFAULT path):
  *   Pass `{ dims: [2], dimsSender: [], dimsReceiver: [], dimsMode: [],
  *            factors: [], data: Float64Array.of(weight, window) }`
@@ -75,25 +91,123 @@ export function buildContextLookup(rows, rowIndices, factors, factorLevels) {
 }
 
 /**
- * Build the context_lookup with explicit timestamp column.
+ * Build the context_lookup with explicit per-row times.
+ *
+ * @param {Float64Array} allTimes  time of every row in `rows` (see parseTimes)
  */
-export function buildContextLookupWithTimes(rows, rowIndices, factors, factorLevels, timesCol) {
-    const nRows   = rowIndices.length;
-    const nFactor = factors.length;
+export function buildContextLookupWithTimes(rows, rowIndices, factors, factorLevels, allTimes) {
+    const ctx = buildContextLookup(rows, rowIndices, factors, factorLevels);
+    for (let i = 0; i < rowIndices.length; i++) ctx.times[i] = allTimes[rowIndices[i]];
+    return ctx;
+}
 
-    const contextLookup = new Int32Array(nRows * nFactor);
-    const times         = new Float64Array(nRows);
+// Seconds per window unit (= rENA.api's mins_to_seconds, hours_to_seconds, ...).
+const SECONDS_PER = { secs: 1, mins: 60, hours: 3600, days: 86400, weeks: 604800 };
 
-    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;
+/**
+ * Seconds per unit of a time-window unit name ('secs', 'mins', 'hours',
+ * 'days', 'weeks'; quotes and a trailing 's' are optional). 'lines' and empty
+ * values return null (no time scaling).
+ */
+export function secondsPerTimeUnit(unit) {
+    if (unit == null) return null;
+    let u = String(unit).replace(/['"]/g, '').trim().toLowerCase();
+    if (u === '' || u === 'lines' || u === 'auto') return null;
+    if (u === 'minutes' || u === 'min') u = 'mins';
+    if (u === 'seconds' || u === 'sec') u = 'secs';
+    if (!u.endsWith('s')) u += 's';
+    if (!(u in SECONDS_PER)) throw new Error(`Unknown time unit '${unit}'`);
+    return SECONDS_PER[u];
+}
+
+const pad2 = (s) => (s.length === 1 ? '0' + s : s);
+
+// Date-time formats rENA.api's parse_date tries, in the same order. Each
+// pattern captures the fields named in `order`; a match is accepted only when
+// the fields form a real date (so 9/17/2013 is rejected as d/m/Y and falls
+// through to m/d/Y, exactly as as.POSIXct returns NA for it in R).
+const DATE_FORMATS = [
+    { re: /^(\d{4})-(\d{2})-(\d{2})$/,                                  order: 'Ymd' },
+    { re: /^(\d{2})\/(\d{2})\/(\d{4})$/,                                order: 'dmY' },
+    { re: /^(\d{2})\/(\d{2})\/(\d{4})$/,                                order: 'mdY' },
+    { re: /^(\d{4})\/(\d{2})\/(\d{2})$/,                                order: 'Ymd' },
+    { re: /^(\d{2})-(\d{2})-(\d{4})$/,                                  order: 'mdY' },
+    { re: /^(\d{2})-(\d{2})-(\d{4})$/,                                  order: 'dmY' },
+    { re: /^(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2})$/,           order: 'YmdHMS' },
+    { re: /^(\d{2})\/(\d{2})\/(\d{4}) (\d{2}):(\d{2}):(\d{2})$/,         order: 'dmYHMS' },
+    { re: /^(\d{2})\/(\d{2})\/(\d{4}) (\d{2}):(\d{2}):(\d{2})$/,         order: 'mdYHMS' },
+    { re: /^(\d{2})\/(\d{2})\/(\d{2}) (\d{2}):(\d{2})$/,                 order: 'mdyHM' },
+    { re: /^(\d{2})\/(\d{2})\/(\d{2}) (\d{2}):(\d{2})$/,                 order: 'dmyHM' },
+    { re: /^(\d{1,2})\/(\d{1,2})\/(\d{4}) (\d{2}):(\d{2})$/,             order: 'mdYHM' },
+    { re: /^(\d{1,2})\/(\d{1,2})\/(\d{2}) (\d{2}):(\d{2})$/,             order: 'mdyHM' },
+];
+
+/**
+ * Parse one time value to seconds (= rENA.api's parse_date): elapsed
+ * "MM:SS" / "HH:MM:SS" → total seconds; a date-time → seconds since the
+ * epoch (UTC). Returns NaN when the value matches no supported format.
+ */
+export function parseTimeValue(value) {
+    let s = String(value).trim();
+    s = s.replace(/ (\d):/g, ' 0$1:')
+         .replace(/^(\d)(\/|-)/, '0$1$2')
+         .replace(/(\/|-)(\d)(\/|-)/g, (_, a, d, b) => a + '0' + d + b);
+
+    let m;
+    if ((m = /^(\d{1,2}):(\d{2})$/.exec(s)))        return (+m[1]) * 60 + (+m[2]);
+    if ((m = /^(\d{1,3}):(\d{2}):(\d{2})$/.exec(s))) return (+m[1]) * 3600 + (+m[2]) * 60 + (+m[3]);
+
+    for (const { re, order } of DATE_FORMATS) {
+        if (!(m = re.exec(s))) continue;
+        const f = { Y: null, m: 1, d: 1, H: 0, M: 0, S: 0 };
+        for (let i = 0; i < order.length; i++) {
+            const v = +m[i + 1];
+            if (order[i] === 'y') f.Y = v <= 68 ? 2000 + v : 1900 + v;  // R's %y pivot
+            else f[order[i]] = v;
         }
+        if (f.m < 1 || f.m > 12 || f.d < 1 || f.H > 23 || f.M > 59 || f.S > 61) continue;
+        const ms = Date.UTC(f.Y, f.m - 1, f.d, f.H, f.M, f.S);
+        if (new Date(ms).getUTCDate() !== f.d) continue;             // e.g. 31/02
+        return ms / 1000;
     }
+    return NaN;
+}
 
-    return { contextLookup, clRows: nRows, clCols: nFactor, times };
+/**
+ * Per-row times, in seconds, for a time column (= rENA.api's handling of
+ * time_column / timeend_column before tma::accumulate). A column whose values
+ * are all numeric is used as-is; otherwise every value is parsed with
+ * parseTimeValue(). With `endCol`, a numeric end column is a duration added
+ * to the start, and any other end column is parsed as the end timestamp.
+ *
+ * @param {Object[]}    rows
+ * @param {string}      col
+ * @param {string|null} [endCol=null]
+ * @returns {Float64Array}
+ * @throws when a value cannot be parsed as a time
+ */
+export function parseTimes(rows, col, endCol = null) {
+    const column = (name) => {
+        const vals = rows.map(r => r[name]);
+        const blank = (v) => v === undefined || v === null || String(v).trim() === '';
+        const nums = vals.map(v => (blank(v) ? NaN : Number(v)));
+        const numeric = nums.every((n, i) => !Number.isNaN(n) || blank(vals[i]));
+        const out = new Float64Array(rows.length);
+        for (let i = 0; i < rows.length; i++) {
+            const t = numeric ? nums[i] : parseTimeValue(vals[i]);
+            if (Number.isNaN(t)) {
+                throw new Error(`Unable to read '${vals[i]}' (row ${i + 1}) in time column '${name}' as a time`);
+            }
+            out[i] = t;
+        }
+        return { out, numeric };
+    };
+
+    const start = column(col).out;
+    if (!endCol) return start;
+    const end = column(endCol);
+    if (end.numeric) for (let i = 0; i < start.length; i++) end.out[i] += start[i];
+    return end.out;
 }
 
 /**
@@ -119,6 +233,79 @@ export function inferFactorLevels(rows, factors) {
     return levels;
 }
 
+// libqe's apply_tensor_unit reads the IS_DEFAULT window as an int, so an
+// infinite window (or one too large for int32) is clamped to INT32_MAX — still
+// longer than any conversation, in lines or in seconds.
+const MAX_WINDOW = 2147483647;
+
+/**
+ * The tensor data libqe accumulates with: windows (the second half of the
+ * column-major data, index 1 along the last axis) converted from `timeUnit`
+ * to seconds when a time column is in use, and infinite / oversized windows
+ * clamped to MAX_WINDOW. Weights are left unchanged.
+ */
+export function resolveTensorData(tensorDef) {
+    const data  = Float64Array.from(tensorDef.data);
+    const nComb = data.length / 2;
+    const scale = tensorDef.timesCol ? (secondsPerTimeUnit(tensorDef.timeUnit) ?? 1) : 1;
+    for (let c = nComb; c < data.length; c++) {
+        const w = data[c] * scale;
+        data[c] = (Number.isNaN(w) || w > MAX_WINDOW) ? MAX_WINDOW : w;
+    }
+    return data;
+}
+
+/**
+ * Per-unit horizon-of-observation contexts (= tma::contexts with rENA.api's
+ * flexible-horizon rules). `horizons.rules` maps each value of the
+ * discriminator column `horizons.by` to the columns that define that
+ * horizon. A row with discriminator value x is in unit U's context when every
+ * rule-x column holds a value U has on at least one of its rows
+ * (`col %in% UNIT$col`); rows whose value has no rule are in no context. Each
+ * unit's context is then split on the union of every rule's columns (NOT on
+ * the discriminator, which only picks the rule), and the moving window runs
+ * within each piece.
+ *
+ * @param {Object[]}   rows
+ * @param {Int32Array} unitOf   unit index per row (-1 = not a modeled unit)
+ * @param {number}     nUnits
+ * @param {{ by: string, rules: Object<string, string[]> }} horizons
+ * @returns {number[][][]}  per unit, its context pieces as ascending row indices
+ */
+export function buildHorizonContexts(rows, unitOf, nUnits, horizons) {
+    const { by, rules } = horizons || {};
+    if (!by) throw new Error('horizons.by (the discriminator column) is required');
+    const ruleCols = new Map();
+    for (const [value, cols] of Object.entries(rules || {})) {
+        if (!Array.isArray(cols) || cols.length === 0) {
+            throw new Error(`horizon '${value}' of '${by}' has no columns assigned`);
+        }
+        ruleCols.set(String(value), cols);
+    }
+    if (ruleCols.size === 0) throw new Error('horizons.rules must define at least one horizon');
+    const splitCols = [...new Set([].concat(...ruleCols.values()))];
+
+    // UNIT$col: every value each unit takes on each rule column.
+    const unitVals = Array.from({ length: nUnits }, () => new Map(splitCols.map(c => [c, new Set()])));
+    for (let i = 0; i < rows.length; i++) {
+        const u = unitOf[i];
+        if (u < 0) continue;
+        for (const c of splitCols) unitVals[u].get(c).add(String(rows[i][c]));
+    }
+
+    return unitVals.map((vals) => {
+        const pieces = new Map();   // split key → row indices (first-appearance order)
+        for (let i = 0; i < rows.length; i++) {
+            const cols = ruleCols.get(String(rows[i][by]));
+            if (!cols || !cols.every(c => vals.get(c).has(String(rows[i][c])))) continue;
+            const key = splitCols.map(c => String(rows[i][c])).join('\u0000');
+            if (!pieces.has(key)) pieces.set(key, []);
+            pieces.get(key).push(i);
+        }
+        return [...pieces.values()];
+    });
+}
+
 /**
  * Accumulate tensor networks for all units across all conversations.
  *
@@ -141,6 +328,9 @@ export function inferFactorLevels(rows, factors) {
  * @param {string|null} [weight=null]  libqe weight model applied per line before
  *                                     the unit sum: 'binary' | 'product' |
  *                                     'sqrt' | 'log1p'
+ * @param {object|null} [horizons=null] flexible horizons (see
+ *                                     buildHorizonContexts); replaces
+ *                                     convoGroups as the windowing contexts
  *
  * @returns {{ networks: Float64Array, rowConnectionCounts: Float64Array }}
  *   networks            nUnits × nConnections, row-major
@@ -150,19 +340,21 @@ export function inferFactorLevels(rows, factors) {
  */
 export function accumulateTensor(qe, rows, codeMatrix, nRows, nCodes, nUnits,
                                   unitOf, convoGroups, tensorDef, ordered = false,
-                                  binary = true, weight = null) {
+                                  binary = true, weight = null, horizons = null) {
     const {
         dims,
         dimsSender   = [],
         dimsReceiver = [],
         dimsMode     = [],
         factors      = [],
-        data:   tensorData,
         timesCol,
+        timesEndCol,
     } = tensorDef;
+    const tensorData = resolveTensorData(tensorDef);
 
     // Resolve factor levels (infer if not provided)
     const factorLevels = tensorDef.factorLevels ?? inferFactorLevels(rows, factors);
+    const allTimes = timesCol ? parseTimes(rows, timesCol, timesEndCol || null) : null;
 
     const nConnections = ordered
         ? nCodes * nCodes
@@ -179,74 +371,91 @@ export function accumulateTensor(qe, rows, codeMatrix, nRows, nCodes, nUnits,
     const receiverArr = new Int32Array(dimsReceiver);
     const modeArr    = new Int32Array(dimsMode);
 
-    for (const [, rowIndices] of convoGroups) {
-        const nConvo = rowIndices.length;
+    // Accumulate `unit`'s response rows (`localRows`, indices into
+    // `rowIndices`) within one context of rows.
+    const accumulateContext = (rowIndices, unit, localRows) => {
+        const nCtx = rowIndices.length;
 
-        // Extract code rows for this conversation
-        const convoCodes = new Float64Array(nConvo * nCodes);
-        for (let r = 0; r < nConvo; r++) {
+        // Extract code rows for this context
+        const ctxCodes = new Float64Array(nCtx * nCodes);
+        for (let r = 0; r < nCtx; r++) {
             const src = rowIndices[r];
-            convoCodes.set(
+            ctxCodes.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)
+        // Build context_lookup and times for this context
+        const { contextLookup, clRows, clCols, times } = allTimes
+            ? buildContextLookupWithTimes(rows, rowIndices, factors, factorLevels, allTimes)
             : buildContextLookup(rows, rowIndices, factors, factorLevels);
 
+        // Always accumulate the DIRECTED per-response-row counts (ordered
+        // kernel), exactly as tma does — it calls apply_tensor with the
+        // default ordered=TRUE and defers the ordered-vs-unordered decision
+        // to aggregation.  Passing the unordered flag here would make the
+        // kernel emit an already-symmetric matrix that the fold below would
+        // then double-count.
+        const result = qe.accumulate_tensor_unit(
+            tensorData, dimsArr,
+            senderArr, receiverArr, modeArr,
+            contextLookup, clRows, clCols,
+            new Int32Array(localRows),
+            ctxCodes, nCtx, nCodes,
+            times,
+            true
+        );
+
+        // 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;
+        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++) {
+                const v = fin.data[finOff + c];
+                rowConnectionCounts[rowOff + c] = v;
+                networks[unitOff + c] += v;
+            }
+        }
+    };
+
+    if (horizons) {
+        // Flexible horizons: every unit has its own contexts.
+        const unitContexts = buildHorizonContexts(rows, unitOf, nUnits, horizons);
+        unitContexts.forEach((pieces, unit) => {
+            for (const rowIndices of pieces) {
+                const localRows = [];
+                for (let r = 0; r < rowIndices.length; r++) {
+                    if (unitOf[rowIndices[r]] === unit) localRows.push(r);
+                }
+                if (localRows.length) accumulateContext(rowIndices, unit, localRows);
+            }
+        });
+        return { networks, rowConnectionCounts };
+    }
+
+    for (const [, rowIndices] of convoGroups) {
         // 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.
+        // but stay in the context for the other units' windows.
         const unitConvoRows = new Map();
-        for (let r = 0; r < nConvo; r++) {
+        for (let r = 0; r < rowIndices.length; 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
         }
-
-        // Accumulate per unit
         for (const [unit, localRows] of unitConvoRows) {
-            const unitRowsArr = new Int32Array(localRows);
-
-            // Always accumulate the DIRECTED per-response-row counts (ordered
-            // kernel), exactly as tma does — it calls apply_tensor with the
-            // default ordered=TRUE and defers the ordered-vs-unordered decision
-            // to aggregation.  Passing the unordered flag here would make the
-            // kernel emit an already-symmetric matrix that the fold below would
-            // then double-count.
-            const result = qe.accumulate_tensor_unit(
-                tensorData, dimsArr,
-                senderArr, receiverArr, modeArr,
-                contextLookup, clRows, clCols,
-                unitRowsArr,
-                convoCodes, nConvo, nCodes,
-                times,
-                true
-            );
-
-            // 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;
-            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++) {
-                    const v = fin.data[finOff + c];
-                    rowConnectionCounts[rowOff + c] = v;
-                    networks[unitOff + c] += v;
-                }
-            }
+            accumulateContext(rowIndices, unit, localRows);
         }
     }