@nirs4all/preflight 0.1.0-alpha.2 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/index.d.ts +5 -1
- package/index.js +327 -13
- package/native/README.md +1 -1
- package/native/nirs4all_preflight_wasm_bg.wasm +0 -0
- package/native/package.json +1 -1
- package/package.json +4 -3
package/README.md
CHANGED
|
@@ -8,4 +8,4 @@ const runtime = await createQualificationRuntime();
|
|
|
8
8
|
const report = runtime.analyze(alreadyAssembledDataset);
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
Use a dedicated worker for large inputs. Cancel by terminating that worker; stale responses must be discarded by the host. No input is sent to a server. This alpha profile is exploratory; advanced validation, clustering and five-language qualification gates remain open. See the capabilities and limitations in each report.
|
|
11
|
+
Use a dedicated worker for large inputs. Cancel by terminating that worker; stale responses must be discarded by the host. No input is sent to a server. This alpha profile is exploratory; advanced validation, clustering qualification and five-language qualification gates remain open. Requires `@nirs4all/methods` with ABI 2.20 (HDBSCAN, ARI, cluster Jaccard, linear sum assignment, PCG64 permutations and Gaussian draws, correlation, exact permutation, Benjamini–Hochberg, PERMANOVA, PERMDISP, energy distance, PCA monitoring and one-way variance components kernels). Root seeds above 2^53 must be passed as a bigint or a decimal string. `analyzeJson(text)` and `validateJson(text)` hand JSON text to the engine unchanged, so no number is rounded or decoded by JavaScript. See the capabilities and limitations in each report.
|
package/index.d.ts
CHANGED
|
@@ -1,8 +1,12 @@
|
|
|
1
1
|
export interface QualificationRuntime {
|
|
2
2
|
analyze(input: unknown): unknown;
|
|
3
3
|
validate(input: unknown): unknown;
|
|
4
|
+
/** JSON text in, report JSON text out; nothing is decoded by JavaScript. */
|
|
5
|
+
analyzeJson(input: string): string;
|
|
6
|
+
validateJson(input: string): string;
|
|
4
7
|
reportHtml(report: unknown): string;
|
|
5
8
|
capabilities(): unknown;
|
|
6
9
|
}
|
|
7
10
|
/** Creates one Rust + Methods instance. Run inside a worker to support cancellation. */
|
|
8
|
-
|
|
11
|
+
/** `dagMlWasmModule` supplies the dag-ml-wasm module bytes (validation probe) where it cannot be fetched. */
|
|
12
|
+
export function createQualificationRuntime(options?: { wasmModule?: BufferSource | WebAssembly.Module; dagMlWasmModule?: BufferSource | WebAssembly.Module }): Promise<QualificationRuntime>;
|
package/index.js
CHANGED
|
@@ -3,12 +3,49 @@
|
|
|
3
3
|
import init, * as rust from './native/nirs4all_preflight_wasm.js';
|
|
4
4
|
import * as methods from '@nirs4all/methods';
|
|
5
5
|
|
|
6
|
+
/** Adapter refusals carry the provider error kind and the same stable
|
|
7
|
+
* reason as the native adapter: `unsupported` for a declared limit,
|
|
8
|
+
* `internal` for a request that breaks the provider contract. */
|
|
9
|
+
const limit = reason => Object.assign(new RangeError(reason), { providerKind: 'unsupported' });
|
|
10
|
+
const invalid = reason => Object.assign(new TypeError(reason), { providerKind: 'internal' });
|
|
11
|
+
|
|
12
|
+
/** Methods exceptions keep their status and context message, mapped to kind
|
|
13
|
+
* and reason by the Rust engine exactly as the native adapter maps
|
|
14
|
+
* n4m_status_t and n4m_context_last_error. */
|
|
15
|
+
function providerError(error) {
|
|
16
|
+
if (error?.providerWire) return error.providerWire;
|
|
17
|
+
if (error instanceof methods.N4mError) return { methods_status: error.status, message: error.message };
|
|
18
|
+
if (error?.providerKind) {
|
|
19
|
+
return { kind: error.providerKind, reason: error.message, ...(error.providerDetail ? { detail: error.providerDetail } : {}) };
|
|
20
|
+
}
|
|
21
|
+
return { kind: 'internal', reason: 'METHODS_CALLBACK_FAILED' };
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/** A failed nested selection travels as its DAG-ML message plus the first
|
|
25
|
+
* error raised by the selection-metrics callback; the Rust engine maps both
|
|
26
|
+
* exactly as the native provider (`dagml::nested_selection_failure`), so the
|
|
27
|
+
* Methods domain message and reason are never duplicated here. */
|
|
28
|
+
const dagFailure = (error, cause) => Object.assign(new Error('DAG_ML_WASM_NESTED_SELECTION_FAILED'), {
|
|
29
|
+
providerWire: { dag_ml_failure: String(error?.message ?? error), cause: cause === undefined ? null : providerError(cause) },
|
|
30
|
+
});
|
|
31
|
+
|
|
32
|
+
/** Optional dag-ml-wasm (nested grouped selection) in the same worker. */
|
|
33
|
+
async function loadDagMl(options) {
|
|
34
|
+
try {
|
|
35
|
+
const dagMl = await import('dag-ml-wasm');
|
|
36
|
+
const { N4mWasmRegressionController } = await import('dag-ml-wasm/n4m-controller');
|
|
37
|
+
await dagMl.default(options.dagMlWasmModule ? { module_or_path: options.dagMlWasmModule } : undefined);
|
|
38
|
+
return { dagMl, N4mWasmRegressionController, version: dagMl.dag_ml_version() };
|
|
39
|
+
} catch (error) {
|
|
40
|
+
return { error: String(error?.message ?? error) };
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
|
|
6
44
|
function matrix(rows) {
|
|
7
45
|
const n = rows.length;
|
|
8
46
|
const p = rows[0]?.length ?? 0;
|
|
9
|
-
if (!n || !p ||
|
|
10
|
-
|
|
11
|
-
}
|
|
47
|
+
if (!n || !p || rows.some(row => row.length !== p)) throw invalid('INVALID_PROVIDER_MATRIX');
|
|
48
|
+
if (n * p > 10_000_000) throw limit('PROVIDER_MEMORY_BUDGET_EXCEEDED');
|
|
12
49
|
return { data: Float64Array.from(rows.flat()), rows: n, cols: p };
|
|
13
50
|
}
|
|
14
51
|
function nested(values, width) {
|
|
@@ -18,25 +55,80 @@ function nested(values, width) {
|
|
|
18
55
|
}
|
|
19
56
|
const nullable = value => Number.isFinite(value) ? value : null;
|
|
20
57
|
|
|
58
|
+
/** The u64 root seed travels as a decimal string: bigint and safe-integer
|
|
59
|
+
* numbers are converted, unsafe numbers are refused (they are already
|
|
60
|
+
* rounded), strings are validated by the Rust engine. */
|
|
61
|
+
function seedAsDecimal(input) {
|
|
62
|
+
const seed = input?.options?.seed;
|
|
63
|
+
if (seed === undefined || typeof seed === 'string') return input;
|
|
64
|
+
if (typeof seed === 'number' && !Number.isSafeInteger(seed)) {
|
|
65
|
+
throw new RangeError('SEED_NOT_SAFE_INTEGER: pass a bigint or a decimal string');
|
|
66
|
+
}
|
|
67
|
+
if (typeof seed !== 'number' && typeof seed !== 'bigint') throw new TypeError('SEED_TYPE');
|
|
68
|
+
return { ...input, options: { ...input.options, seed: seed.toString() } };
|
|
69
|
+
}
|
|
70
|
+
|
|
21
71
|
/** Create in a worker; the host cancels by terminating that worker. */
|
|
22
72
|
export async function createQualificationRuntime(options = {}) {
|
|
23
73
|
await init(options.wasmModule ? { module_or_path: options.wasmModule } : undefined);
|
|
24
74
|
await methods.loadModule();
|
|
25
75
|
const abi = methods.abiVersion();
|
|
26
|
-
if (abi[0] !== 2 || abi[1] <
|
|
76
|
+
if (abi[0] !== 2 || abi[1] < 20) throw new Error('METHODS_ABI_2_20_REQUIRED');
|
|
27
77
|
const backend_version = methods.version();
|
|
28
|
-
const
|
|
78
|
+
const dag = await loadDagMl(options);
|
|
79
|
+
const methodsCapabilities = ['pca', 'repeatability', 'summary', 'nearest_neighbors', 'local_contrast', 'hdbscan', 'adjusted_rand_index', 'cluster_jaccard', 'linear_sum_assignment', 'random_permutations', 'multivariate_normal', 'snv', 'noise_proxy', 'tolerance_pairs', 'association', 'holm_adjust', 'correlation', 'bh_adjust', 'association_exact', 'correlation_exact', 'permanova', 'permdisp', 'permanova_freedman_lane', 'energy_distance', 'pca_monitor', 'variance_components', 'group_means', 'regression_scores'].map(id => ({
|
|
29
80
|
capability_id: `methods.${id}`, available: true, qualified: false,
|
|
30
81
|
reason: `${backend_version}; alpha protocol`,
|
|
31
82
|
}));
|
|
32
|
-
const
|
|
83
|
+
const dispatch = (operation, payload) => {
|
|
33
84
|
const request = JSON.parse(payload);
|
|
34
85
|
let result;
|
|
35
86
|
switch (operation) {
|
|
36
87
|
case 'capabilities': result = methodsCapabilities; break;
|
|
88
|
+
case 'procedure': {
|
|
89
|
+
const spec = methods.manifest().methods.find(item => item.method_id === request.method_id);
|
|
90
|
+
if (!spec) throw limit('METHODS_PROCEDURE_UNAVAILABLE');
|
|
91
|
+
if (spec.kind !== 'procedure' || !spec.roles.includes('generic')) throw invalid('PROCEDURE_GENERIC_ROLE_REQUIRED');
|
|
92
|
+
const procedure = new (methods.methodClass(request.method_id))();
|
|
93
|
+
for (const [name, parameter] of Object.entries(request.parameters ?? {})) {
|
|
94
|
+
if (procedure.paramTypes[name] !== parameter.kind) throw invalid('PROCEDURE_INVALID_PARAMETER');
|
|
95
|
+
const { kind, value } = parameter;
|
|
96
|
+
if (kind === 'double' && !Number.isFinite(value)
|
|
97
|
+
|| kind === 'int' && !Number.isSafeInteger(value)
|
|
98
|
+
|| kind === 'double_array' && (!Array.isArray(value) || value.length > 10_000_000 || value.some(v => !Number.isFinite(v)))
|
|
99
|
+
|| kind === 'int_array' && (!Array.isArray(value) || value.length > 10_000_000 || value.some(v => !Number.isSafeInteger(v)))) {
|
|
100
|
+
throw invalid('PROCEDURE_INVALID_PARAMETER_VALUE');
|
|
101
|
+
}
|
|
102
|
+
procedure.params[name] = value;
|
|
103
|
+
}
|
|
104
|
+
const x = matrix(request.matrix);
|
|
105
|
+
if (x.data.some(v => !Number.isFinite(v))) throw invalid('INVALID_PROVIDER_MATRIX');
|
|
106
|
+
const reference = request.reference ? matrix(request.reference) : undefined;
|
|
107
|
+
if (reference && reference.cols !== x.cols) throw invalid('PROCEDURE_REFERENCE_WIDTH_MISMATCH');
|
|
108
|
+
if (reference?.data.some(v => !Number.isFinite(v))) throw invalid('INVALID_PROVIDER_MATRIX');
|
|
109
|
+
const values = procedure.run(x, undefined, reference ? { XTarget: reference } : {});
|
|
110
|
+
const outputs = {};
|
|
111
|
+
for (const [name, value] of Object.entries(values)) {
|
|
112
|
+
if (typeof value === 'number') {
|
|
113
|
+
if (!Number.isFinite(value)) throw invalid('PROCEDURE_NONFINITE_RESULT');
|
|
114
|
+
outputs[name] = { kind: 'scalar', value };
|
|
115
|
+
} else if (Array.isArray(value)) {
|
|
116
|
+
if (value.length > 10_000_000 || value.some(v => !Number.isSafeInteger(v))) throw invalid('PROCEDURE_INVALID_INTEGER_RESULT');
|
|
117
|
+
outputs[name] = { kind: 'integer_vector', data: value };
|
|
118
|
+
} else {
|
|
119
|
+
const { rows, cols, data } = value;
|
|
120
|
+
if (!Number.isSafeInteger(rows) || !Number.isSafeInteger(cols) || rows < 0 || cols < 0
|
|
121
|
+
|| rows * cols > 10_000_000 || rows * cols !== data.length) throw invalid('PROCEDURE_INVALID_RESULT_SHAPE');
|
|
122
|
+
if (data.some(v => !Number.isFinite(v))) throw invalid('PROCEDURE_NONFINITE_RESULT');
|
|
123
|
+
outputs[name] = { kind: 'matrix', rows, cols, data: Array.from(data) };
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
result = { outputs, backend_version };
|
|
127
|
+
break;
|
|
128
|
+
}
|
|
37
129
|
case 'pca': {
|
|
38
130
|
const output = methods.preflightPca(matrix(request.matrix), request.n_components);
|
|
39
|
-
result = { eigenvalues: Array.from(output.eigenvalues), scores: nested(output.scores.data, output.scores.cols), full_moments: output.fullMoments, backend_version };
|
|
131
|
+
result = { eigenvalues: Array.from(output.eigenvalues), scores: nested(output.scores.data, output.scores.cols), full_moments: output.fullMoments, resolution: output.resolution, unresolved: Array.from(output.unresolved, Boolean), backend_version };
|
|
40
132
|
break;
|
|
41
133
|
}
|
|
42
134
|
case 'repeatability': {
|
|
@@ -45,14 +137,14 @@ export async function createQualificationRuntime(options = {}) {
|
|
|
45
137
|
break;
|
|
46
138
|
}
|
|
47
139
|
case 'summary': {
|
|
48
|
-
if (!request.values.length || request.values.length > 10_000_000) throw
|
|
140
|
+
if (!request.values.length || request.values.length > 10_000_000) throw invalid('INVALID_SUMMARY_VALUES');
|
|
49
141
|
const output = methods.preflightSummary(Float64Array.from(request.values));
|
|
50
142
|
result = { count: output[0], min: output[1], max: output[2], mean: output[3], sample_sd: nullable(output[4]), q25: output[5], median: output[6], q75: output[7], backend_version };
|
|
51
143
|
break;
|
|
52
144
|
}
|
|
53
145
|
case 'nearest_neighbors': {
|
|
54
146
|
const query = matrix(request.query), reference = matrix(request.reference);
|
|
55
|
-
if (query.rows * reference.rows * query.cols > 250_000_000 || request.k > 100) throw
|
|
147
|
+
if (query.rows * reference.rows * query.cols > 250_000_000 || request.k > 100) throw limit('KNN_SHAPE_OR_WORK_BUDGET_EXCEEDED');
|
|
56
148
|
const output = methods.preflightNearestNeighbors(query, reference, request.k, request.query_group_ids, request.reference_group_ids);
|
|
57
149
|
result = { indices: nested(output.indices, output.k), distances: nested(Array.from(output.distances, nullable), output.k), backend_version };
|
|
58
150
|
break;
|
|
@@ -62,13 +154,235 @@ export async function createQualificationRuntime(options = {}) {
|
|
|
62
154
|
result = { contrast: nullable(output.contrast), fraction_rows_with_neighbors: output.fractionRowsWithNeighbors, observed_same_class_fraction: nullable(output.observedSameClassFraction), expected_same_class_fraction: nullable(output.expectedSameClassFraction), backend_version };
|
|
63
155
|
break;
|
|
64
156
|
}
|
|
65
|
-
|
|
157
|
+
case 'hdbscan': {
|
|
158
|
+
const x = matrix(request.matrix);
|
|
159
|
+
if (x.rows * x.rows * x.cols > 2.5e9) throw limit('HDBSCAN_SHAPE_OR_WORK_BUDGET');
|
|
160
|
+
const output = methods.clusterHdbscan(x, { minClusterSize: request.min_cluster_size, minSamples: request.min_samples, selection: request.selection, allowSingleCluster: request.allow_single_cluster });
|
|
161
|
+
const tree = output.tree.map(node => ({
|
|
162
|
+
parent: node.parent < 0 ? null : node.parent, size: node.size, label: node.label < 0 ? null : node.label,
|
|
163
|
+
birth_distance: node.parent < 0 ? null : 1 / node.lambdaBirth, death_distance: 1 / node.lambdaDeath, stability: nullable(node.stability),
|
|
164
|
+
}));
|
|
165
|
+
result = { labels: output.labels, membership: Array.from(output.membership), outlier_scores: Array.from(output.outlierScores, nullable), persistence: Array.from(output.persistence), tree, backend_version };
|
|
166
|
+
break;
|
|
167
|
+
}
|
|
168
|
+
case 'adjusted_rand_index': {
|
|
169
|
+
if (request.labels_a.length > 10_000_000) throw limit('ARI_SHAPE_OR_WORK_BUDGET');
|
|
170
|
+
result = { ari: nullable(methods.preflightAdjustedRandIndex(request.labels_a, request.labels_b)), backend_version };
|
|
171
|
+
break;
|
|
172
|
+
}
|
|
173
|
+
case 'cluster_jaccard': {
|
|
174
|
+
const ka = request.n_clusters_a, kb = request.n_clusters_b;
|
|
175
|
+
if (request.labels_a.length > 10_000_000 || ka * kb > 10_000_000) throw new RangeError('JACCARD_WORK_BUDGET');
|
|
176
|
+
const output = methods.clusterJaccardMatrix(request.labels_a, request.labels_b, ka, kb);
|
|
177
|
+
const rows = values => kb ? nested(values, kb) : Array.from({ length: ka }, () => []);
|
|
178
|
+
result = { jaccard: rows(Array.from(output.jaccard.data, nullable)), intersections: rows(output.intersections), sizes_a: output.sizesA, sizes_b: output.sizesB, backend_version };
|
|
179
|
+
break;
|
|
180
|
+
}
|
|
181
|
+
case 'linear_sum_assignment': {
|
|
182
|
+
const cost = { data: Float64Array.from(request.cost.flat()), rows: request.cost.length, cols: request.cost[0]?.length ?? 0 };
|
|
183
|
+
if (!cost.rows || !cost.cols || cost.rows * cost.cols * Math.min(cost.rows, cost.cols) > 1e8) throw new RangeError('ASSIGNMENT_WORK_BUDGET');
|
|
184
|
+
const output = methods.linearSumAssignment(cost, request.maximize);
|
|
185
|
+
result = { row_indices: output.rowInd, column_indices: output.colInd, backend_version };
|
|
186
|
+
break;
|
|
187
|
+
}
|
|
188
|
+
case 'random_permutations': {
|
|
189
|
+
if (request.n * request.n_permutations > 10_000_000) throw new RangeError('PERMUTATION_WORK_BUDGET');
|
|
190
|
+
result = { permutations: methods.randomPermutations(BigInt(request.seed), request.n, request.n_permutations), backend_version };
|
|
191
|
+
break;
|
|
192
|
+
}
|
|
193
|
+
case 'multivariate_normal': {
|
|
194
|
+
const d = request.mean.length;
|
|
195
|
+
if (request.n_samples * d > 10_000_000) throw new RangeError('MULTIVARIATE_NORMAL_BUDGET');
|
|
196
|
+
const output = methods.randomMultivariateNormal(Float64Array.from(request.mean), matrix(request.covariance), request.n_samples, BigInt(request.seed));
|
|
197
|
+
result = { samples: nested(output.data, d), backend_version };
|
|
198
|
+
break;
|
|
199
|
+
}
|
|
200
|
+
case 'snv': {
|
|
201
|
+
// Methods SNV (row mean, population SD) with per-row rounding bounds.
|
|
202
|
+
const groups = request.group_ids ? request.group_ids.reduce((a, b) => Math.max(a, b), -1) + 1 : undefined;
|
|
203
|
+
const output = methods.preflightSnv(matrix(request.matrix), request.group_ids ?? undefined, groups);
|
|
204
|
+
result = { matrix: nested(output.matrix.data, output.matrix.cols), error_bounds: Array.from(output.errorBounds), backend_version };
|
|
205
|
+
break;
|
|
206
|
+
}
|
|
207
|
+
case 'noise_proxy': {
|
|
208
|
+
const x = matrix(request.matrix);
|
|
209
|
+
const output = methods.preflightNoiseProxy(x, request.window_length, request.polyorder, Uint8Array.from(request.valid_mask.flat(), Boolean));
|
|
210
|
+
result = { band_noise: Array.from(output.bandNoise, nullable), band_counts: output.bandCounts, pooled: nullable(output.pooled), residual_gain: output.gain, backend_version };
|
|
211
|
+
break;
|
|
212
|
+
}
|
|
213
|
+
case 'tolerance_pairs': {
|
|
214
|
+
const query = matrix(request.query);
|
|
215
|
+
const reference = request.reference ? matrix(request.reference) : undefined;
|
|
216
|
+
const n = query.rows, work = reference ? n * reference.rows : n * (n - 1) / 2;
|
|
217
|
+
if (work * query.cols > 250_000_000 || request.max_pairs > 1_000_000) throw limit('TOLERANCE_PAIRS_SHAPE_OR_WORK_BUDGET_EXCEEDED');
|
|
218
|
+
const output = methods.preflightPairsWithinTolerance(query, request.tolerance, request.max_pairs, reference, request.query_group_ids, reference ? request.reference_group_ids : undefined);
|
|
219
|
+
result = { pairs: nested(output.pairs, 2), distances: Array.from(output.distances), query_flags: Array.from(output.queryFlags, Boolean), reference_flags: Array.from(output.referenceFlags, Boolean), total_pairs: output.totalPairs, candidate_pairs: output.candidatePairs, backend_version };
|
|
220
|
+
break;
|
|
221
|
+
}
|
|
222
|
+
case 'association': {
|
|
223
|
+
// Seeds travel as decimal strings so no u64 is rounded by JSON.
|
|
224
|
+
const output = methods.preflightFactorAssociation(request.factor_codes, Float64Array.from(request.targets), request.categorical, request.n_permutations, BigInt(request.seed));
|
|
225
|
+
result = { effect_size: nullable(output.effectSize), statistic: nullable(output.statistic), df1: nullable(output.df1), df2: nullable(output.df2), n_levels: output.nLevels, n_target_values: output.nTargetValues, log10_distinct_permutations: output.log10DistinctPermutations, p_value: nullable(output.pValue), n_at_least_observed: output.nAtLeastObserved, n_permutations_executed: output.nPermutationsExecuted, backend_version };
|
|
226
|
+
break;
|
|
227
|
+
}
|
|
228
|
+
case 'permanova': {
|
|
229
|
+
const x = matrix(request.matrix);
|
|
230
|
+
const output = methods.statsPermanova(x, request.term_codes, request.strata_codes ?? undefined, request.n_permutations, BigInt(request.seed));
|
|
231
|
+
result = { ss_binary_exponent: output.ssExponent, ss_total: output.ssTotal, ss_strata: output.ssStrata, ss_term: output.ssTerm, ss_residual: output.ssResidual, r2: nullable(output.r2), partial_r2: nullable(output.partialR2), pseudo_f: nullable(output.pseudoF), df_term: output.dfTerm, df_residual: output.dfResidual, n_levels: output.nLevels, n_strata: output.nStrata, log10_distinct_permutations: output.log10DistinctPermutations, p_value: nullable(output.pValue), residual_resolution: nullable(output.residualResolution), f_numerically_unresolved: output.fNumericallyUnresolved, n_at_least_observed: output.nAtLeastObserved, n_permutations_executed: output.nPermutationsExecuted, backend_version };
|
|
232
|
+
break;
|
|
233
|
+
}
|
|
234
|
+
case 'permanova_freedman_lane': {
|
|
235
|
+
const x = matrix(request.matrix);
|
|
236
|
+
const output = methods.statsPermanovaFreedmanLane(x, request.term_codes, request.condition_codes, request.n_permutations, BigInt(request.seed));
|
|
237
|
+
result = { ss_binary_exponent: output.ssExponent, ss_total: output.ssTotal, ss_reduced: output.ssReduced, ss_term: output.ssTerm, ss_residual: output.ssResidual, r2: nullable(output.r2), partial_r2: nullable(output.partialR2), pseudo_f: nullable(output.pseudoF), df_term: output.dfTerm, df_residual: output.dfResidual, rank_reduced: output.rankReduced, log10_distinct_permutations: output.log10DistinctPermutations, p_value: nullable(output.pValue), residual_resolution: nullable(output.residualResolution), f_numerically_unresolved: output.fNumericallyUnresolved, n_at_least_observed: output.nAtLeastObserved, n_permutations_executed: output.nPermutationsExecuted, backend_version };
|
|
238
|
+
break;
|
|
239
|
+
}
|
|
240
|
+
case 'permdisp': {
|
|
241
|
+
const x = matrix(request.matrix);
|
|
242
|
+
const output = methods.statsPermdisp(x, request.group_codes, request.n_permutations, BigInt(request.seed));
|
|
243
|
+
result = { distance_binary_exponent: output.distanceExponent, distances: Array.from(output.distances), group_mean_distances: Array.from(output.groupMeanDistances), f: nullable(output.f), df1: output.df1, df2: output.df2, n_groups: output.nGroups, log10_distinct_permutations: output.log10DistinctPermutations, p_value: nullable(output.pValue), residual_resolution: nullable(output.residualResolution), f_numerically_unresolved: output.fNumericallyUnresolved, n_at_least_observed: output.nAtLeastObserved, n_permutations_executed: output.nPermutationsExecuted, backend_version };
|
|
244
|
+
break;
|
|
245
|
+
}
|
|
246
|
+
case 'energy_distance': {
|
|
247
|
+
// Same budgets as the native adapter, before any WASM allocation.
|
|
248
|
+
const n = request.matrix.length, g = request.n_groups;
|
|
249
|
+
const pairs = n * (n - 1) / 2;
|
|
250
|
+
if (pairs > 20_000_000 || g * g > 10_000_000 || pairs * ((request.matrix[0]?.length ?? 0) + request.n_permutations + 1) > 2.5e9) throw limit('ENERGY_DISTANCE_WORK_BUDGET');
|
|
251
|
+
const output = methods.statsEnergyDistance(matrix(request.matrix), request.group_codes, g, request.n_permutations, BigInt(request.seed));
|
|
252
|
+
result = { energy: nested(output.energy, g), energy_bounds: nested(output.energyBounds, g), mean_distances: nested(output.meanDistances, g), statistic: output.statistic, statistic_bound: output.statisticBound, log10_distinct_permutations: output.log10DistinctPermutations, p_value: nullable(output.pValue), p_value_conservative: nullable(output.pValueConservative), n_at_least_observed: output.nAtLeastObserved, n_permutations_executed: output.nPermutationsExecuted, n_undecidable: output.nUndecidable, backend_version };
|
|
253
|
+
break;
|
|
254
|
+
}
|
|
255
|
+
case 'pca_monitor': {
|
|
256
|
+
const reference = matrix(request.reference), monitored = matrix(request.monitored);
|
|
257
|
+
if ((reference.rows + monitored.rows) * reference.cols > 10_000_000) throw limit('PCA_MONITOR_WORK_BUDGET');
|
|
258
|
+
const output = methods.statsPcaMonitor(reference, monitored, request.max_components, request.n_folds, request.alpha);
|
|
259
|
+
const k = output.effectiveComponents;
|
|
260
|
+
result = { effective_components: k, eigenvalues: Array.from(output.eigenvalues.slice(0, k)), reference_t2: Array.from(output.referenceT2, nullable), reference_q: Array.from(output.referenceQ), monitored_t2: Array.from(output.monitoredT2, nullable), monitored_q: Array.from(output.monitoredQ), t2_limit: nullable(output.t2Limit), q_limit: output.qLimit, tolerance: output.tolerance, condition: output.condition, q_tolerance_scale: output.qToleranceScale, eigenvalue_resolution: output.eigenvalueResolution, n_beyond_t2: output.nBeyondT2, n_beyond_q: output.nBeyondQ, n_beyond_either: output.nBeyondEither, n_near_t2: output.nNearT2, n_near_q: output.nNearQ, n_near_either: output.nNearEither, reference_total_variance: output.referenceTotalVariance, monitored_total_variance: nullable(output.monitoredTotalVariance), centroid_distance: output.centroidDistance, centroid_subspace_distance: output.centroidSubspaceDistance, centroid_residual_distance: output.centroidResidualDistance, centroid_t2: nullable(output.centroidT2), retained_fraction: nullable(output.retainedFraction), backend_version };
|
|
261
|
+
break;
|
|
262
|
+
}
|
|
263
|
+
case 'holm_adjust': {
|
|
264
|
+
result = { adjusted: Array.from(methods.preflightHolmAdjust(Float64Array.from(request.p_values))), backend_version };
|
|
265
|
+
break;
|
|
266
|
+
}
|
|
267
|
+
case 'correlation': {
|
|
268
|
+
const output = methods.statsCorrelationTest(Float64Array.from(request.x), Float64Array.from(request.y), request.method, request.n_permutations, BigInt(request.seed));
|
|
269
|
+
result = { coefficient: nullable(output.coefficient), n_distinct_x: output.nDistinctX, n_distinct_y: output.nDistinctY, log10_distinct_permutations: output.log10DistinctPermutations, p_value: nullable(output.pValue), n_at_least_observed: output.nAtLeastObserved, n_permutations_executed: output.nPermutationsExecuted, backend_version };
|
|
270
|
+
break;
|
|
271
|
+
}
|
|
272
|
+
case 'association_exact': {
|
|
273
|
+
const output = methods.statsFactorAssociationExact(request.factor_codes, Float64Array.from(request.targets), request.categorical, request.max_arrangements);
|
|
274
|
+
result = { n_arrangements: output.nArrangements, p_value: nullable(output.pValue), minimum_p_value: nullable(output.minimumPValue), maximum_statistic: nullable(output.maximumStatistic), backend_version };
|
|
275
|
+
break;
|
|
276
|
+
}
|
|
277
|
+
case 'correlation_exact': {
|
|
278
|
+
const output = methods.statsCorrelationExact(Float64Array.from(request.x), Float64Array.from(request.y), request.method, request.max_arrangements);
|
|
279
|
+
result = { n_arrangements: output.nArrangements, p_value: nullable(output.pValue), minimum_p_value: nullable(output.minimumPValue), maximum_statistic: nullable(output.maximumStatistic), backend_version };
|
|
280
|
+
break;
|
|
281
|
+
}
|
|
282
|
+
case 'group_means': {
|
|
283
|
+
const output = methods.statsGroupMeans(matrix(request.matrix), request.group_codes, request.n_groups);
|
|
284
|
+
result = { means: nested(output.means.data, output.means.cols), counts: output.counts, backend_version };
|
|
285
|
+
break;
|
|
286
|
+
}
|
|
287
|
+
case 'regression_scores': {
|
|
288
|
+
if (!request.y_true.length || request.y_true.length !== request.y_pred.length) throw invalid('INVALID_REGRESSION_SCORES_REQUEST');
|
|
289
|
+
const output = methods.statsRegressionScores(Float64Array.from(request.y_true), Float64Array.from(request.y_pred));
|
|
290
|
+
result = { rmse: output.rmse, mae: output.mae, r2: nullable(output.r2), r2_exponent: output.r2Exponent, backend_version };
|
|
291
|
+
break;
|
|
292
|
+
}
|
|
293
|
+
case 'validation_capabilities': {
|
|
294
|
+
result = [{ capability_id: 'validation.nested_grouped_probe', available: !dag.error, qualified: false,
|
|
295
|
+
reason: dag.error ? 'DAG_ML_WASM_UNAVAILABLE' : `dag-ml-wasm ${dag.version}; alpha protocol` }];
|
|
296
|
+
break;
|
|
297
|
+
}
|
|
298
|
+
case 'nested_selection': {
|
|
299
|
+
// Transport only: DAG-ML owns the loops, Methods RolePipeline fits.
|
|
300
|
+
if (dag.error) throw limit('DAG_ML_WASM_UNAVAILABLE');
|
|
301
|
+
const { request: nestedRequest, envelope, rows } = request;
|
|
302
|
+
const index = new Map(rows.sample_ids.map((id, i) => [id, i]));
|
|
303
|
+
const pick = (ids, values) => {
|
|
304
|
+
if (ids.some(id => !index.has(id))) throw invalid('UNKNOWN_PROBE_SAMPLE');
|
|
305
|
+
return matrix(ids.map(id => values(index.get(id))));
|
|
306
|
+
};
|
|
307
|
+
const operators = Object.fromEntries(nestedRequest.graph.nodes.map(node => [node.id, { type: node.operator.type }]));
|
|
308
|
+
const controller = new dag.N4mWasmRegressionController({
|
|
309
|
+
methods, operators,
|
|
310
|
+
resolveFeatures: ({ view }) => ({ sampleIds: [...view.sample_ids], matrix: pick(view.sample_ids, i => rows.x[i]) }),
|
|
311
|
+
resolveTargets: ({ sampleIds }) => ({ sampleIds: [...sampleIds], matrix: pick(sampleIds, i => [rows.y[i]]) }),
|
|
312
|
+
});
|
|
313
|
+
try {
|
|
314
|
+
let outcome, cause;
|
|
315
|
+
try {
|
|
316
|
+
// Selection metrics come from Methods; DAG-ML keeps the
|
|
317
|
+
// comparison and the tie rule. mse is the square of the RMSE.
|
|
318
|
+
// The first error raised here is kept as the failure cause.
|
|
319
|
+
const metrics = (name, payload) => {
|
|
320
|
+
try {
|
|
321
|
+
const { y_true, y_pred } = JSON.parse(payload);
|
|
322
|
+
const s = methods.statsRegressionScores(Float64Array.from(y_true), Float64Array.from(y_pred));
|
|
323
|
+
if (name === 'rmse') return s.rmse;
|
|
324
|
+
if (name === 'mse') return s.rmse * s.rmse;
|
|
325
|
+
if (name === 'mae') return s.mae;
|
|
326
|
+
throw invalid('UNSUPPORTED_SELECTION_METRIC');
|
|
327
|
+
} catch (error) {
|
|
328
|
+
cause ??= error;
|
|
329
|
+
throw error;
|
|
330
|
+
}
|
|
331
|
+
};
|
|
332
|
+
outcome = dag.dagMl.execute_nested_selection_json(JSON.stringify(nestedRequest),
|
|
333
|
+
JSON.stringify([controller.manifest(dag.dagMl)]), JSON.stringify(envelope), controller.callback, metrics);
|
|
334
|
+
} catch (error) {
|
|
335
|
+
throw dagFailure(error, cause);
|
|
336
|
+
}
|
|
337
|
+
result = JSON.parse(outcome);
|
|
338
|
+
} finally {
|
|
339
|
+
controller.close();
|
|
340
|
+
}
|
|
341
|
+
break;
|
|
342
|
+
}
|
|
343
|
+
case 'bh_adjust': {
|
|
344
|
+
result = { adjusted: Array.from(methods.statsBhAdjust(Float64Array.from(request.p_values))), backend_version };
|
|
345
|
+
break;
|
|
346
|
+
}
|
|
347
|
+
case 'variance_components': {
|
|
348
|
+
// Seeds travel as decimal strings so no u64 is rounded by JSON.
|
|
349
|
+
const x = matrix(request.matrix);
|
|
350
|
+
const validMask = Uint8Array.from(request.valid_mask.flat(), Boolean);
|
|
351
|
+
const point = methods.statsVarianceComponentsReml(x, request.group_ids, validMask);
|
|
352
|
+
const ci = methods.statsVarianceComponentsIntervals(x, request.group_ids, {
|
|
353
|
+
confidence: request.confidence, nBootstrap: request.n_bootstrap, seed: BigInt(request.seed),
|
|
354
|
+
clusterIds: request.cluster_ids ?? undefined, validMask,
|
|
355
|
+
});
|
|
356
|
+
const pairs = values => Array.from({ length: x.cols }, (_, j) => [nullable(values[2 * j]), nullable(values[2 * j + 1])]);
|
|
357
|
+
result = {
|
|
358
|
+
sigma2_between: Array.from(point.sigma2Between, nullable), sigma2_within: Array.from(point.sigma2Within, nullable),
|
|
359
|
+
icc: Array.from(point.icc, nullable), reml_log_likelihood: Array.from(point.logLikelihood, nullable),
|
|
360
|
+
n_groups: point.nGroups, n_observations: point.nObservations, reml_candidates: point.remlCandidates,
|
|
361
|
+
bisection_iterations: point.bisectionIterations, status: Array.from(point.status),
|
|
362
|
+
sd_ci_chi_square: pairs(ci.sdChiSquare), icc_ci_exact_f: pairs(ci.iccExactF),
|
|
363
|
+
sd_ci_bootstrap: pairs(ci.sdBootstrap), icc_ci_bootstrap: pairs(ci.iccBootstrap),
|
|
364
|
+
n_valid_replicates: ci.nValidReplicates, backend_version,
|
|
365
|
+
};
|
|
366
|
+
break;
|
|
367
|
+
}
|
|
368
|
+
default: throw limit('METHODS_OPERATION_UNSUPPORTED');
|
|
369
|
+
}
|
|
370
|
+
return result;
|
|
371
|
+
};
|
|
372
|
+
const callback = (operation, payload) => {
|
|
373
|
+
try {
|
|
374
|
+
return JSON.stringify({ ok: dispatch(operation, payload) });
|
|
375
|
+
} catch (error) {
|
|
376
|
+
return JSON.stringify({ provider_error: providerError(error) });
|
|
66
377
|
}
|
|
67
|
-
return JSON.stringify(result);
|
|
68
378
|
};
|
|
69
379
|
return {
|
|
70
|
-
analyze: input => JSON.parse(rust.analyze_json(JSON.stringify(input), callback)),
|
|
71
|
-
validate: input => JSON.parse(rust.validate_json(JSON.stringify(input))),
|
|
380
|
+
analyze: input => JSON.parse(rust.analyze_json(JSON.stringify(seedAsDecimal(input)), callback)),
|
|
381
|
+
validate: input => JSON.parse(rust.validate_json(JSON.stringify(seedAsDecimal(input)))),
|
|
382
|
+
// JSON-text entry points: the text reaches the Rust parser unchanged, so
|
|
383
|
+
// nothing is rounded or decoded by JavaScript (u64 seeds, reserved Y).
|
|
384
|
+
analyzeJson: text => rust.analyze_json(text, callback),
|
|
385
|
+
validateJson: text => rust.validate_json(text),
|
|
72
386
|
reportHtml: report => rust.report_html_json(JSON.stringify(report)),
|
|
73
387
|
capabilities: () => JSON.parse(rust.capabilities_json(callback)),
|
|
74
388
|
};
|
package/native/README.md
CHANGED
|
@@ -8,4 +8,4 @@ const runtime = await createQualificationRuntime();
|
|
|
8
8
|
const report = runtime.analyze(alreadyAssembledDataset);
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
Use a dedicated worker for large inputs. Cancel by terminating that worker; stale responses must be discarded by the host. No input is sent to a server. This alpha profile is exploratory; advanced validation, clustering and five-language qualification gates remain open. See the capabilities and limitations in each report.
|
|
11
|
+
Use a dedicated worker for large inputs. Cancel by terminating that worker; stale responses must be discarded by the host. No input is sent to a server. This alpha profile is exploratory; advanced validation, clustering qualification and five-language qualification gates remain open. Requires `@nirs4all/methods` with ABI 2.20 (HDBSCAN, ARI, cluster Jaccard, linear sum assignment, PCG64 permutations and Gaussian draws, correlation, exact permutation, Benjamini–Hochberg, PERMANOVA, PERMDISP, energy distance, PCA monitoring and one-way variance components kernels). Root seeds above 2^53 must be passed as a bigint or a decimal string. `analyzeJson(text)` and `validateJson(text)` hand JSON text to the engine unchanged, so no number is rounded or decoded by JavaScript. See the capabilities and limitations in each report.
|
|
Binary file
|
package/native/package.json
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"name": "nirs4all-preflight-wasm",
|
|
3
3
|
"type": "module",
|
|
4
4
|
"description": "WebAssembly binding for nirs4all qualification protocols",
|
|
5
|
-
"version": "0.1.
|
|
5
|
+
"version": "0.1.1",
|
|
6
6
|
"license": "CECILL-2.1 OR AGPL-3.0-or-later",
|
|
7
7
|
"repository": {
|
|
8
8
|
"type": "git",
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nirs4all/preflight",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "Rust NIRS dataset qualification with reusable Methods diagnostics",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "(CECILL-2.1 OR AGPL-3.0-or-later)",
|
|
@@ -27,11 +27,12 @@
|
|
|
27
27
|
"THIRD_PARTY_NOTICES.md"
|
|
28
28
|
],
|
|
29
29
|
"dependencies": {
|
|
30
|
-
"@nirs4all/methods": "1.3.
|
|
30
|
+
"@nirs4all/methods": "1.3.10",
|
|
31
|
+
"dag-ml-wasm": "0.3.43"
|
|
31
32
|
},
|
|
32
33
|
"scripts": {
|
|
33
34
|
"build:native": "wasm-pack build . --target web --out-dir native --release && node scripts/prepare-native.mjs",
|
|
34
|
-
"test": "node --test tests/*.test.mjs",
|
|
35
|
+
"test": "node --test --experimental-test-module-mocks tests/*.test.mjs",
|
|
35
36
|
"prepack": "npm run build:native"
|
|
36
37
|
},
|
|
37
38
|
"publishConfig": {
|