v0.1.0 — WebAssembly bindings for libqe — shared C++ core for Quantitative Ethnography

@qe-libs/libqe-wasm

WebAssembly bindings for libqe — the shared C++ core for Quantitative Ethnography packages.

Exposes the full libqe API as a zero-dependency ES module usable in browsers and Node.js.

Install

# one-time: tell npm where to find the @qe-libs scope
echo "@qe-libs:registry=https://gitlab.com/api/v4/projects/epistemic-analytics%2Fqe-packages%2Flibqe/packages/npm/" >> ~/.npmrc

npm install @qe-libs/libqe-wasm

Usage

import loadLibQE from '@qe-libs/libqe-wasm';

const qe = await loadLibQE();

// Code-pair labels
qe.connection_names(['Concept A', 'Concept B', 'Concept C']);
// → ['Concept A & Concept B', 'Concept A & Concept C', 'Concept B & Concept C']

// Stanza-window accumulation
const codes = new Float64Array([1,1,0,  1,0,1,  0,1,1]);  // 3×3 row-major
const out   = qe.accumulate_stanza(codes, 3, 3, /*back=*/2, /*forward=*/0, /*binary=*/true, /*ordered=*/false);
// out → { data: Float64Array, rows: 3, cols: 3 }

// Group confidence interval
const points = new Float64Array([0.1,0.2, 0.3,0.4, 0.5,0.6]);  // 3 units × 2 dims
const ci = qe.mean_ci(points, 3, 2, 0.95);
// ci → { data: Float64Array, rows: 2, cols: 3 }  — [mean, lower, upper] per dim

// Outlier interval (IQR × 1.5)
const oi = qe.outlier_ci(points, 3, 2, 1.5);
// oi → { data: Float64Array, rows: 2, cols: 2 }  — [lower, upper] per dim

Matrix convention

All matrix inputs are flat Float64Array in row-major order with explicit rows and cols arguments. Return values are plain objects:

{ data: Float64Array, rows: number, cols: number }

Access a cell: data[row * cols + col]

API reference

Adjacency

Function	Description
`connection_names(names)`	`string[]` → pair labels `["A & B", ...]`
`connection_indices(len)`	Upper-triangle index pairs `{ rows, cols }`
`code_connections(data, n_codes)`	Code vector → connection vector
`fold_directed_network(data)`	n² directed vector → upper-tri
`network_to_vector(data, rows, cols, full)`	Matrix → flat vector

Normalization

Function	Description
`normalize_networks(data, rows, cols)`	Row-wise L2 normalization
`scale_networks(data, rows, cols)`	Max-norm scaling

Modeling

Function	Description
`center_points(data, rows, cols)`	Subtract column means
`mean_ci(data, rows, cols, conf_level)`	t-based CI → `n_dims × 3` `[mean, lower, upper]`
`outlier_ci(data, rows, cols, iqr_factor)`	IQR-based interval → `n_dims × 2` `[lower, upper]`
`ena_correlation(pts, pr, pc, cen, cr, cc, conf_level)`	Pearson r + CI → `n_units × 3` `[r, lower, upper]`
`node_positions(adj, ar, ac, t, tr, tc, dims)`	Undirected ENA node positions. `dims` may be omitted or `0` to use all columns of `t`
`directed_node_positions(lw, lr, lc, pt, pr, pc, dims)`	Directed ENA node positions. `dims` may be omitted or `0` to use all columns of `pt`
`directed_node_positions_combine_pairs(lw, lr, lc, pt, pr, pc, dims)`	Directed ENA — ground+response rows averaged before solve. `dims` may be omitted or `0`

Accumulation

Function	Description
`connection_matrix(ground, gn, response, rn, weight, ordered)`	Core adjacency math for one ground+response pair → `n_codes × n_codes` matrix
`accumulate_stanza(data, rows, cols, back, forward, binary, ordered)`	Stanza-window. `ordered=false`: upper-tri `choose(n,2)` cols. `ordered=true`: directed `n²` cols
`row_connections(data, rows, cols, binary)`	Per-row co-occurrence
`rolling_window_sum(data, rows, cols, window_size)`	Rolling backward sum
`flat_index(indices, dims)`	Column-major linear index
`accumulate_unit(codes, rows, cols, unit_rows, decay_fn, ordered)`	Ground/response accumulation for one unit (tma). `decay_fn(Float64Array) → Float64Array`
`accumulate_unit_with_rows(codes, rows, cols, unit_rows, decay_fn, ordered)`	Like `accumulate_unit` but also returns per-response-row networks → `{ networks, row_networks }`
`accumulate_tensor_unit(tensor, dims, dims_sender, dims_receiver, dims_mode, context_lookup, cl_rows, cl_cols, unit_rows, codes, rows, cols, times, ordered)`	tma tensor accumulation for one unit → `{ connection_counts: Float64Array, row_connection_counts: matObj }`. All index arrays are 0-based Int32Array; `tensor` is flat column-major `Float64Array`; `context_lookup` is row-major `Int32Array (n_context_rows × n_factors)`

Rotation

Function	Description
`ena_svd(data, rows, cols)`	SVD rotation → `{ rotation, eigenvalues, column_names }`
`deflate(data, rows, cols, axis)`	Project out a given axis → `{ data, rows, cols }`
`orthogonal_svd(data, rows, cols, weights, wr, wc, labels)`	Weighted SVD with orthogonalization
`complete_rotation(data, rows, cols, axes, ax_rows, ax_cols, labels)`	Fix named axes then fill remaining with SVD
`means_rotation(data, rows, cols, group_pairs)`	Group-means rotation. `group_pairs`: `Array<{a: Int32Array, b: Int32Array}>` (0-based row indices)
`generalized_means_rotation(V, vr, vc, xm, xr, xc, x_target, x1_cols, x_categorical, x_n_groups, x_subset, has_y, ym, yr, yc, y_target, y1_cols, y_categorical, y_n_groups, n_lambda, k_folds, lasso_eps)`	Lasso-based GMR. Index arrays are `Int32Array` (0-based); pass zero-length `Int32Array` for `x_subset` to use all rows. Returns `{ rotation, eigenvalues, column_names }` with labels `GMR1`, `GMR2`\	`SVD2`, …

Building from source

Prerequisites

Emscripten (emcc on PATH)
Conan 2.x (pip install conan)
CMake ≥ 3.18, Ninja

Steps

# From the libqe repo root:
sh wasm/scripts/build.sh

# Output: wasm/dist/libqe.js  wasm/dist/libqe.wasm

The build uses ../include/libqe/ headers directly — no Conan registry fetch needed. Conan is only used to install Armadillo for the Emscripten cross-compilation.

Notes on Armadillo and BLAS

libqe uses Armadillo for linear algebra. The WASM build compiles with ARMA_DONT_USE_BLAS and ARMA_DONT_USE_LAPACK so Armadillo uses its own built-in LU/QR routines instead of calling external symbols that Emscripten cannot resolve. For ENA's typical data sizes this has no meaningful performance impact.

Running tests

cd wasm
npm ci
npm test   # requires dist/ — run build first