@nirs4all/methods 1.0.17 → 1.1.0

package/dist/index.d.ts

@@ -1,9 +1,16 @@
 export { loadModule, getModule, makeMatrixView, readArrayView } from "./ffi.js";
 export { Context } from "./context.js";
 export { Config } from "./config.js";
-export { Model, fitPls, predictPls, fitModel, predictModel, fitAom, fitPop, fitAomRidge, fitAomStack, computeSplit, computeSplitIndices, type PlsModel, type FittedModel, type AomModel, type PopModel, type AomRidgeOptions, type AomStackOptions, type SplitKind, type SplitOptions, type SplitIndices } from "./model.js";
+export { Model, fitPls, predictPls, fitModel, predictModel, fitAom, fitAomChain, fitPop, fitAomRidge, fitAomStack, computeSplit, computeSplitIndices, type PlsModel, type FittedModel, type AomModel, type AomChainDescriptor, type AomChainModel, type PopModel, type AomRidgeOptions, type AomStackOptions, type SplitKind, type SplitOptions, type SplitIndices } from "./model.js";
 export { ppCreate, ppFit, ppTransform, ppGetState, ppSetState, ppDestroy, type PpOperator, } from "./preprocessing.js";
 export { MethodResult } from "./methodResult.js";
+export { NativeModel } from "./nativeModel.js";
+export { NativeEstimator, NativeMethod, NativeProcedure, manifest, methodClass, type Augmenter, type Classifier, type FitInputs, type Fold, type ParamType, type ParamValue, type ProbabilisticClassifier, type Procedure, type ProcedureOutput, type Regressor, type SampleFilter, type Selector, type Splitter, type TargetMixingAugmenter, type Transformer } from "./estimatorRoles.js";
+export * from "./estimatorRolesGenerated.js";
+export { splitNative, type NativeSplitterKind, type NativeSplitterOptions, type NativeSplitIndices } from "./nativeSplitter.js";
+export { augmentNative, type NativeAugmentationKind } from "./nativeAugmentation.js";
+export { NativePreprocessingPipeline, PipelineOperatorKind, type PipelineStep, } from "./nativePreprocessingPipeline.js";
+export { selectSpa, selectVariables, selectorMethods } from "./selection.js";
 export { inspectN4mm, SERIALIZED_MODEL_INFO_SCHEMA_V1, SERIALIZED_MODEL_CAPABILITY_PREDICT, SERIALIZED_MODEL_CAPABILITY_TRANSFORM, SERIALIZED_MODEL_CAPABILITY_AFFINE, SERIALIZED_MODEL_CAPABILITY_PIPELINE, PipelineFingerprintAlgorithm, PipelineSemanticProfile, SerializedSavitzkyGolayMode, SerializedPipelineOperatorKind, type SerializedModelInfo, type SerializedPipelineInfo, } from "./serialization.js";
 export { Status, Dtype, Algorithm, Solver, Deflation, N4mError, type Matrix, } from "./types.js";
 /** ABI / project version reported by the loaded WASM module. */

package/dist/index.js

@@ -13,9 +13,16 @@ import { getModule } from "./ffi.js";
 export { loadModule, getModule, makeMatrixView, readArrayView } from "./ffi.js";
 export { Context } from "./context.js";
 export { Config } from "./config.js";
-export { Model, fitPls, predictPls, fitModel, predictModel, fitAom, fitPop, fitAomRidge, fitAomStack, computeSplit, computeSplitIndices } from "./model.js";
+export { Model, fitPls, predictPls, fitModel, predictModel, fitAom, fitAomChain, fitPop, fitAomRidge, fitAomStack, computeSplit, computeSplitIndices } from "./model.js";
 export { ppCreate, ppFit, ppTransform, ppGetState, ppSetState, ppDestroy, } from "./preprocessing.js";
 export { MethodResult } from "./methodResult.js";
+export { NativeModel } from "./nativeModel.js";
+export { NativeEstimator, NativeMethod, NativeProcedure, manifest, methodClass } from "./estimatorRoles.js";
+export * from "./estimatorRolesGenerated.js";
+export { splitNative } from "./nativeSplitter.js";
+export { augmentNative } from "./nativeAugmentation.js";
+export { NativePreprocessingPipeline, PipelineOperatorKind, } from "./nativePreprocessingPipeline.js";
+export { selectSpa, selectVariables, selectorMethods } from "./selection.js";
 export { inspectN4mm, SERIALIZED_MODEL_INFO_SCHEMA_V1, SERIALIZED_MODEL_CAPABILITY_PREDICT, SERIALIZED_MODEL_CAPABILITY_TRANSFORM, SERIALIZED_MODEL_CAPABILITY_AFFINE, SERIALIZED_MODEL_CAPABILITY_PIPELINE, PipelineFingerprintAlgorithm, PipelineSemanticProfile, SerializedSavitzkyGolayMode, SerializedPipelineOperatorKind, } from "./serialization.js";
 export { Status, Dtype, Algorithm, Solver, Deflation, N4mError, } from "./types.js";
 /** ABI / project version reported by the loaded WASM module. */

package/dist/methodResult.d.ts

@@ -22,6 +22,8 @@ export declare class MethodResult {
     matrix(name: string): Matrix;
     /** Read a named int32 vector. */
     vectorInt(name: string): Int32Array;
+    /** Read a named int64 vector without narrowing its elements to JS numbers. */
+    vectorInt64(name: string): BigInt64Array;
     /** Read a named scalar (returns NaN if not present). */
     scalar(name: string): number;
     destroy(): void;

package/dist/methodResult.js

@@ -73,7 +73,7 @@ export class MethodResult {
             m.stringToUTF8(name, namePtr, nameBytes + 1);
             const status = m.ccall("n4m_method_result_get_double_matrix", "number", ["number", "number", "number", "number", "number"], [this._ptr, namePtr, dataPtrPtr, rowsPtr, colsPtr]);
             checkStatus(status);
-            const dataPtr = m.getValue(dataPtrPtr, "i32");
+            const dataPtr = m.getValue(dataPtrPtr, "i32") >>> 0;
             // i64 lo/hi pair — WASM_BIGINT=1 returns BigInt; use HEAP32 instead.
             const rows = m.getValue(rowsPtr, "i64");
             const cols = m.getValue(colsPtr, "i64");
@@ -116,6 +116,38 @@ export class MethodResult {
             m._free(sizePtr);
         }
     }
+    /** Read a named int64 vector without narrowing its elements to JS numbers. */
+    vectorInt64(name) {
+        const m = getModule();
+        const nameBytes = m.lengthBytesUTF8(name);
+        const namePtr = m._malloc(nameBytes + 1);
+        const dataPtrPtr = m._malloc(4);
+        const sizePtr = m._malloc(8);
+        try {
+            m.stringToUTF8(name, namePtr, nameBytes + 1);
+            const status = m.ccall("n4m_method_result_get_int64_vector", "number", ["number", "number", "number", "number"], [this._ptr, namePtr, dataPtrPtr, sizePtr]);
+            checkStatus(status);
+            const dataPtr = m.getValue(dataPtrPtr, "i32") >>> 0;
+            const size64 = BigInt(m.getValue(sizePtr, "i64"));
+            if (size64 < 0n || size64 > BigInt(Number.MAX_SAFE_INTEGER)) {
+                throw new RangeError(`Invalid int64 vector length for '${name}'.`);
+            }
+            const size = Number(size64);
+            if (dataPtr < 0 || size > Math.floor((m.HEAPU8.byteLength - dataPtr) / 8)) {
+                throw new RangeError(`Invalid int64 vector buffer for '${name}'.`);
+            }
+            const out = new BigInt64Array(size);
+            const view = new DataView(m.HEAPU8.buffer, m.HEAPU8.byteOffset + dataPtr, size * 8);
+            for (let i = 0; i < size; i += 1)
+                out[i] = view.getBigInt64(i * 8, true);
+            return out;
+        }
+        finally {
+            m._free(namePtr);
+            m._free(dataPtrPtr);
+            m._free(sizePtr);
+        }
+    }
     /** Read a named scalar (returns NaN if not present). */
     scalar(name) {
         const m = getModule();

package/dist/model.d.ts

@@ -44,7 +44,10 @@ export interface FittedModel {
  * @param X row-major (n × p) input matrix.
  * @param Y row-major (n × q) target matrix.
  * @param n_components number of latent components (used by the PLS family).
- * @param params positional hyper-parameter vector for the model.
+ * @param params positional hyper-parameter vector for the model. For
+ *   GroupSparsePLS this is `[group_lambda, ...group_assignment]`, with exactly
+ *   one non-negative integer group ID per input feature; no implicit grouping
+ *   is applied.
  */
 export declare function fitModel(model: string, X: Matrix, Y: Matrix, n_components: number, params?: number[]): FittedModel;
 /** Predict from a fitted {@link FittedModel} for new X (row-major n_new × p). */
@@ -59,6 +62,31 @@ export interface AomModel extends FittedModel {
     /** Best internal-CV score of the selected operator. */
     score: number;
 }
+export interface AomChainDescriptor {
+    /** Chain boundaries in the flattened operator list (n_chains + 1). */
+    chainOffsets: number[];
+    /** Flattened n4m_operator_kind_t values. */
+    operatorKinds: number[];
+    /** Parameter boundaries in the flattened parameter list (n_ops + 1). */
+    parameterOffsets: number[];
+    /** Flattened operator parameters. */
+    parameters: number[];
+}
+export interface AomChainModel extends FittedModel {
+    selectedChain: number;
+    selectedParameter: number;
+    score: number;
+}
+/** Fit one PLS or Ridge head with the configurable native AOM chain sweep.
+ * The exact same descriptor can be evaluated by an external HPO implementation,
+ * making search-space parity explicit and auditable. */
+export declare function fitAomChain(X: Matrix, Y: Matrix, descriptor: AomChainDescriptor, options: {
+    nFolds?: number;
+    head: "ridge" | "pls";
+    ridgeLambdas?: number[];
+    plsComponents?: number[];
+    momentPolicy?: "auto" | "materialized" | "moments";
+}): AomChainModel;
 /** Fit AOM-PLS (operator-adaptive PLS) on (X, Y).
  *
  * Screens a bank of strict-linear preprocessing operators by internal k-fold CV

package/dist/model.js

@@ -106,7 +106,10 @@ export function predictPls(model, X_new) {
  * @param X row-major (n × p) input matrix.
  * @param Y row-major (n × q) target matrix.
  * @param n_components number of latent components (used by the PLS family).
- * @param params positional hyper-parameter vector for the model.
+ * @param params positional hyper-parameter vector for the model. For
+ *   GroupSparsePLS this is `[group_lambda, ...group_assignment]`, with exactly
+ *   one non-negative integer group ID per input feature; no implicit grouping
+ *   is applied.
  */
 export function fitModel(model, X, Y, n_components, params = []) {
     if (X.rows !== Y.rows) {
@@ -134,7 +137,7 @@ export function fitModel(model, X, Y, n_components, params = []) {
             coefsBuf.ptr, xmBuf.ptr, ymBuf.ptr, interBuf.ptr,
             hasInterBuf, 0]);
         checkStatus(status);
-        // Only models with a genuine affine intercept (currently Ridge) report
+        // Only models with a genuine affine intercept (Ridge and MBPLS) report
         // has_intercept=1; the PLS/PCR family and the PLS-based Tier-B fits
         // predict via the centred form and carry no intercept (kept null so a
         // caller never adds a misleading zero/y_mean term to x.B).
@@ -176,7 +179,7 @@ export function predictModel(model, X_new) {
     // AOM-PLS (and any future affine model) carries input-space coefficients +
     // a genuine intercept and zero means — it predicts on RAW X via the
     // explicit-intercept form  pred = intercept + x.B. Every centred model
-    // (PLS family + the Tier-B fits, including Ridge) carries intercept = null
+    // (PLS family + centred Tier-B fits) carries intercept = null
     // and predicts via  pred = y_mean + (x - x_mean).B. The C helper picks the
     // form from whether the intercept pointer is non-NULL.
     const useIntercept = model.intercept !== null;
@@ -208,6 +211,69 @@ export function predictModel(model, X_new) {
             M._free(interBuf.ptr);
     }
 }
+/** Fit one PLS or Ridge head with the configurable native AOM chain sweep.
+ * The exact same descriptor can be evaluated by an external HPO implementation,
+ * making search-space parity explicit and auditable. */
+export function fitAomChain(X, Y, descriptor, options) {
+    if (X.rows !== Y.rows)
+        throw new Error(`X.rows (${X.rows}) must equal Y.rows (${Y.rows})`);
+    const { chainOffsets, operatorKinds, parameterOffsets, parameters } = descriptor;
+    if (chainOffsets.length < 2 || operatorKinds.length < 1 || parameterOffsets.length !== operatorKinds.length + 1) {
+        throw new Error("Invalid AOM chain descriptor");
+    }
+    const ridgeLambdas = options.ridgeLambdas ?? [];
+    const plsComponents = options.plsComponents ?? [];
+    if (options.head === "ridge" && ridgeLambdas.length < 1)
+        throw new Error("Ridge AOM requires ridgeLambdas");
+    if (options.head === "pls" && plsComponents.length < 1)
+        throw new Error("PLS AOM requires plsComponents");
+    const M = getModule();
+    const n = X.rows, p = X.cols, q = Y.cols;
+    const xBuf = _malloc_f64(M, n * p), yBuf = _malloc_f64(M, n * q);
+    const chainBuf = M._malloc(chainOffsets.length * 4);
+    const kindsBuf = M._malloc(operatorKinds.length * 4);
+    const offsetsBuf = M._malloc(parameterOffsets.length * 4);
+    const paramsBuf = parameters.length > 0 ? _malloc_f64(M, parameters.length).ptr : 0;
+    const ridgeBuf = ridgeLambdas.length > 0 ? _malloc_f64(M, ridgeLambdas.length).ptr : 0;
+    const plsBuf = plsComponents.length > 0 ? M._malloc(plsComponents.length * 4) : 0;
+    const coefsBuf = _malloc_f64(M, p * q), interBuf = _malloc_f64(M, q);
+    const selectedBuf = M._malloc(4), parameterBuf = _malloc_f64(M, 1), scoreBuf = _malloc_f64(M, 1);
+    try {
+        _copy_in(M, X.data, xBuf.ptr);
+        _copy_in(M, Y.data, yBuf.ptr);
+        M.HEAP32.set(Int32Array.from(chainOffsets), chainBuf >> 2);
+        M.HEAP32.set(Int32Array.from(operatorKinds), kindsBuf >> 2);
+        M.HEAP32.set(Int32Array.from(parameterOffsets), offsetsBuf >> 2);
+        if (paramsBuf !== 0)
+            M.HEAPF64.set(Float64Array.from(parameters), paramsBuf >>> 3);
+        if (ridgeBuf !== 0)
+            M.HEAPF64.set(Float64Array.from(ridgeLambdas), ridgeBuf >>> 3);
+        if (plsBuf !== 0)
+            M.HEAP32.set(Int32Array.from(plsComponents), plsBuf >> 2);
+        const status = M.ccall("n4m_wasm_aom_chain_fit", "number", Array(25).fill("number"), [xBuf.ptr, yBuf.ptr, n, p, q, options.nFolds ?? 5,
+            chainBuf, chainOffsets.length, kindsBuf, operatorKinds.length,
+            offsetsBuf, parameterOffsets.length, paramsBuf, parameters.length,
+            ridgeBuf, ridgeLambdas.length, plsBuf, plsComponents.length,
+            options.head === "ridge" ? 1 : 2,
+            options.momentPolicy === "materialized" ? 1 : options.momentPolicy === "moments" ? 2 : 0,
+            coefsBuf.ptr, interBuf.ptr, selectedBuf, parameterBuf.ptr, scoreBuf.ptr]);
+        checkStatus(status);
+        return {
+            coefficients: _read_out(M, coefsBuf.ptr, p * q),
+            xMean: new Float64Array(p), yMean: new Float64Array(q),
+            intercept: _read_out(M, interBuf.ptr, q),
+            n_features: p, n_targets: q,
+            selectedChain: M.HEAP32[selectedBuf >> 2] ?? -1,
+            selectedParameter: _read_out(M, parameterBuf.ptr, 1)[0] ?? NaN,
+            score: _read_out(M, scoreBuf.ptr, 1)[0] ?? NaN,
+        };
+    }
+    finally {
+        [xBuf.ptr, yBuf.ptr, chainBuf, kindsBuf, offsetsBuf, paramsBuf, ridgeBuf, plsBuf,
+            coefsBuf.ptr, interBuf.ptr, selectedBuf, parameterBuf.ptr, scoreBuf.ptr]
+            .filter((ptr) => ptr !== 0).forEach((ptr) => M._free(ptr));
+    }
+}
 /** Fit AOM-PLS (operator-adaptive PLS) on (X, Y).
  *
  * Screens a bank of strict-linear preprocessing operators by internal k-fold CV