@winkjs/composer 0.0.2 → 0.4.1

package/src/tools/training/features.js

@@ -0,0 +1,227 @@
+// src/tools/training/features.js
+
+/**
+ * @fileoverview Declarative feature extraction for physics-informed models.
+ *
+ * Three schema builders describe how to extract features from raw records:
+ *   group()   — aggregate across symmetric channels (enforces physics symmetry)
+ *   scalar()  — extract a single numeric value
+ *   counter() — count entries satisfying a predicate
+ *
+ * buildExtractor() compiles a schema into { extract, names, width }.
+ * The compiled extract() produces a fixed-width numeric vector from each
+ * record, suitable for logistic regression or any classifier.
+ *
+ * Design principle: group() is the physics constraint — it aggregates
+ * per-channel values into layer-level statistics, making the model
+ * structurally unable to learn channel-specific preferences.
+ */
+
+const GROUP = 'group';
+const SCALAR = 'scalar';
+const COUNTER = 'counter';
+
+const AVAILABLE_STATS = [ 'max', 'sum', 'countAbove' ];
+
+/**
+ * Schema builder: aggregate across symmetric channels.
+ *
+ * The group constraint enforces physics symmetry — the model sees
+ * layer-level aggregates, not individual channel values. Each stat
+ * becomes a separate feature named `{name}_{stat}`.
+ *
+ * @param {string} name — base name for generated features (e.g. 'mass').
+ * @param {string[]} ids — channel identifiers (e.g. ['T1', 'T3', 'T4']).
+ * @param {Function} accessor — ( record, id ) → number. Extracts a value per channel.
+ * @param {object} [options] — { stats: string[], countAboveThreshold: number }.
+ * @returns {object} column descriptor.
+ */
+const group = function ( name, ids, accessor, options ) {
+    if ( typeof name !== 'string' || name.length === 0 ) {
+        throw new Error( 'features.group: name must be a non-empty string' );
+    }
+    if ( !Array.isArray( ids ) || ids.length === 0 ) {
+        throw new Error( 'features.group: ids must be a non-empty array' );
+    }
+    if ( typeof accessor !== 'function' ) {
+        throw new Error( 'features.group: accessor must be a function' );
+    }
+
+    const stats = ( options && Array.isArray( options.stats ) ) ?
+        options.stats :
+        [ 'max', 'sum', 'countAbove' ];
+
+    for ( let i = 0; i < stats.length; i += 1 ) {
+        if ( AVAILABLE_STATS.indexOf( stats[ i ] ) === -1 ) {
+            throw new Error(
+                'features.group: unknown stat "' + stats[ i ] +
+                '". Available: ' + AVAILABLE_STATS.join( ', ' )
+            );
+        }
+    }
+
+    const countAboveThreshold = ( options && options.countAboveThreshold !== undefined ) ?
+        options.countAboveThreshold :
+        1.5;
+
+    if ( typeof countAboveThreshold !== 'number' ) {
+        throw new Error( 'features.group: countAboveThreshold must be a number' );
+    }
+
+    return {
+        type: GROUP,
+        name: name,
+        ids: ids,
+        accessor: accessor,
+        stats: stats,
+        countAboveThreshold: countAboveThreshold
+    };
+};
+
+/**
+ * Schema builder: extract a single numeric value.
+ *
+ * Use for features that are already aggregate or unique (e.g. T6 coupling
+ * z-score, cross-tank Mahalanobis distance).
+ *
+ * @param {string} name — feature name.
+ * @param {Function} accessor — ( record ) → number.
+ * @returns {object} column descriptor.
+ */
+const scalar = function ( name, accessor ) {
+    if ( typeof name !== 'string' || name.length === 0 ) {
+        throw new Error( 'features.scalar: name must be a non-empty string' );
+    }
+    if ( typeof accessor !== 'function' ) {
+        throw new Error( 'features.scalar: accessor must be a function' );
+    }
+    return { type: SCALAR, name: name, accessor: accessor };
+};
+
+/**
+ * Schema builder: count entries satisfying a predicate.
+ *
+ * Unlike group(), the set of items is dynamic — determined at extraction
+ * time from the source object's keys. Use for violation counts where the
+ * item set may vary per record.
+ *
+ * @param {string} name — feature name.
+ * @param {Function} sourceAccessor — ( record ) → object. Returns the source object.
+ * @param {Function} predicate — ( entry ) → boolean. Tests each value.
+ * @returns {object} column descriptor.
+ */
+const counter = function ( name, sourceAccessor, predicate ) {
+    if ( typeof name !== 'string' || name.length === 0 ) {
+        throw new Error( 'features.counter: name must be a non-empty string' );
+    }
+    if ( typeof sourceAccessor !== 'function' ) {
+        throw new Error( 'features.counter: sourceAccessor must be a function' );
+    }
+    if ( typeof predicate !== 'function' ) {
+        throw new Error( 'features.counter: predicate must be a function' );
+    }
+    return { type: COUNTER, name: name, sourceAccessor: sourceAccessor, predicate: predicate };
+};
+
+/**
+ * Compile a feature schema into an extractor.
+ *
+ * Validates the schema for structural consistency (unique names, known
+ * column types) and returns a compiled { extract, names, width } object.
+ *
+ * @param {object[]} schema — array of column descriptors from group/scalar/counter.
+ * @returns {{ extract: Function, names: string[], width: number }}
+ */
+const buildExtractor = function ( schema ) {
+    if ( !Array.isArray( schema ) || schema.length === 0 ) {
+        throw new Error( 'features.buildExtractor: schema must be a non-empty array' );
+    }
+
+    // Build feature names from schema
+    const names = [];
+    for ( let i = 0; i < schema.length; i += 1 ) {
+        const col = schema[ i ];
+        if ( col.type === GROUP ) {
+            for ( let s = 0; s < col.stats.length; s += 1 ) {
+                names.push( col.name + '_' + col.stats[ s ] );
+            }
+        } else if ( col.type === SCALAR || col.type === COUNTER ) {
+            names.push( col.name );
+        } else {
+            throw new Error(
+                'features.buildExtractor: unknown column type "' +
+                String( col.type ) + '" at index ' + i
+            );
+        }
+    }
+
+    // Validate unique names
+    const seen = Object.create( null );
+    for ( let i = 0; i < names.length; i += 1 ) {
+        if ( seen[ names[ i ] ] ) {
+            throw new Error(
+                'features.buildExtractor: duplicate feature name "' + names[ i ] + '"'
+            );
+        }
+        seen[ names[ i ] ] = true;
+    }
+
+    const width = names.length;
+
+    /**
+     * Extract a fixed-width feature vector from a record.
+     * @param {object} record — raw input record.
+     * @returns {number[]} feature vector of length `width`.
+     */
+    const extract = function ( record ) {
+        const v = new Array( width );
+        let idx = 0;
+
+        for ( let i = 0; i < schema.length; i += 1 ) {
+            const col = schema[ i ];
+
+            if ( col.type === GROUP ) {
+                let max = 0;
+                let sum = 0;
+                let countAbove = 0;
+
+                for ( let j = 0; j < col.ids.length; j += 1 ) {
+                    const val = col.accessor( record, col.ids[ j ] );
+                    if ( val > max ) max = val;
+                    sum += val;
+                    if ( val > col.countAboveThreshold ) countAbove += 1;
+                }
+
+                for ( let s = 0; s < col.stats.length; s += 1 ) {
+                    const stat = col.stats[ s ];
+                    if ( stat === 'max' ) {
+                        v[ idx ] = max;
+                    } else if ( stat === 'sum' ) {
+                        v[ idx ] = sum;
+                    } else {
+                        v[ idx ] = countAbove;
+                    }
+                    idx += 1;
+                }
+            } else if ( col.type === SCALAR ) {
+                v[ idx ] = col.accessor( record );
+                idx += 1;
+            } else {
+                const source = col.sourceAccessor( record );
+                const keys = Object.keys( source );
+                let count = 0;
+                for ( let k = 0; k < keys.length; k += 1 ) {
+                    if ( col.predicate( source[ keys[ k ] ] ) ) count += 1;
+                }
+                v[ idx ] = count;
+                idx += 1;
+            }
+        }
+
+        return v;
+    };
+
+    return { extract: extract, names: names, width: width };
+};
+
+export { group, scalar, counter, buildExtractor };

package/src/tools/training/index.js

@@ -0,0 +1,21 @@
+// src/tools/training/index.js
+
+/**
+ * @fileoverview Public API for the training utility.
+ *
+ * Re-exports scaling, logistic regression, and evaluation metrics
+ * as a flat namespace. Intended for offline model training workflows —
+ * the learned coefficients feed into flow configuration (e.g. the future
+ * `infer` node).
+ */
+
+export {
+    computeStandardParams,
+    computeMinMaxParams,
+    computeRobustParams,
+    scale,
+    standardize
+} from './scale.js';
+
+export { sigmoid, train, predict, classify } from './logistic.js';
+export { confusionMatrix, classificationMetrics, sweepThresholds } from './metrics.js';

package/src/tools/training/logistic.js

@@ -0,0 +1,238 @@
+// src/tools/training/logistic.js
+
+/**
+ * @fileoverview Logistic regression via batch gradient descent with L2
+ * regularization and class weighting.
+ *
+ * Implements the standard binary logistic model (Bishop, 2006, PRML §4.3):
+ *     P(y=1 | x) = σ( wᵀx + b )
+ *
+ * Training minimises the weighted cross-entropy loss with optional L2
+ * penalty (ridge). The data term is averaged by 1/n while the L2 penalty
+ * is not — this makes lambda dataset-size-invariant: the same lambda
+ * produces the same coefficients regardless of n (when data is replicated).
+ * Class weights automatically balance imbalanced datasets by making the
+ * effective sample count equal across classes.
+ *
+ * Convergence uses relative loss change: |Δloss| / max(1, |prevLoss|),
+ * with a minimum iteration guard to avoid premature exit.
+ *
+ * Hot-path arrays (pHat, grad) are pre-allocated once — zero allocations
+ * inside the training loop.
+ *
+ * Reference:
+ *   Bishop, C. M. (2006). Pattern Recognition and Machine Learning.
+ *   Springer. Chapter 4.3 — Probabilistic Discriminative Models.
+ */
+
+import { validateMatrix, validateBinaryLabels } from './validate.js';
+
+// ── Sigmoid ───────────────────────────────────────────────────────
+
+const SIGMOID_UPPER = 1 - 1e-15;
+const SIGMOID_LOWER = 1e-15;
+
+/**
+ * Logistic sigmoid, clamped to [-500, 500] to prevent exp overflow.
+ * Never returns exact 0 or 1 — prevents log(p) from producing -Infinity.
+ *
+ * @param {number} z — Linear predictor.
+ * @returns {number} σ(z) ∈ (1e-15, 1 - 1e-15).
+ */
+const sigmoid = function ( z ) {
+    if ( z > 500 ) return SIGMOID_UPPER;
+    if ( z < -500 ) return SIGMOID_LOWER;
+    return 1 / ( 1 + Math.exp( -z ) );
+}; // sigmoid()
+
+// ── Defaults ──────────────────────────────────────────────────────
+
+const DEFAULTS = Object.freeze( {
+    learningRate: 0.1,
+    maxIter: 1000,
+    minIter: 5,
+    lambda: 0.01,
+    classWeight: null,
+    convergenceTol: 1e-6
+} );
+
+// ── Train ─────────────────────────────────────────────────────────
+
+/**
+ * Train a binary logistic regression model.
+ *
+ * @param {number[][]} X — Feature matrix (n × p), already scaled.
+ * @param {number[]}   y — Label vector, each element exactly 0 or 1.
+ * @param {object}     [options] — Training hyper-parameters.
+ * @param {number}     [options.learningRate=0.1]
+ * @param {number}     [options.maxIter=1000]
+ * @param {number}     [options.minIter=5]         — Minimum iterations before convergence check.
+ * @param {number}     [options.lambda=0.01]       — L2 regularization strength.
+ * @param {string|null} [options.classWeight=null]  — 'auto' or null.
+ * @param {number}     [options.convergenceTol=1e-6]
+ * @returns {{ coefficients: Float64Array, intercept: number, loss: number, iterations: number }}
+ */
+const train = function ( X, y, options ) {
+    // ── Validate ──────────────────────────────────────────────────
+    const { n, p } = validateMatrix( X, 'train' );
+    validateBinaryLabels( y, n, 'train' );
+
+    // ── Options ───────────────────────────────────────────────────
+    const opts = Object.assign( Object.create( null ), DEFAULTS, options );
+    const alpha = opts.learningRate;
+    const maxIter = opts.maxIter;
+    const minIter = opts.minIter;
+    const lambda = opts.lambda;
+    const tol = opts.convergenceTol;
+
+    // ── Class weights ─────────────────────────────────────────────
+    // Auto-compute: w_k = n / (2 × n_k)  — equalises effective counts.
+    const w = new Float64Array( 2 ); // w[0] = weight for class 0, w[1] for class 1
+    if ( opts.classWeight === 'auto' ) {
+        let n1 = 0;
+        for ( let i = 0; i < n; i += 1 ) n1 += y[ i ];
+        const n0 = n - n1;
+        if ( n0 === 0 || n1 === 0 ) {
+            throw new Error( 'train: y must contain both classes (0 and 1).' );
+        }
+        w[ 0 ] = n / ( 2 * n0 );
+        w[ 1 ] = n / ( 2 * n1 );
+    } else {
+        w[ 0 ] = 1;
+        w[ 1 ] = 1;
+    }
+
+    // ── Initialise ────────────────────────────────────────────────
+    const coefficients = new Float64Array( p ); // zeros
+    let intercept = 0;
+
+    // Pre-allocated working arrays — zero allocations in the loop.
+    const pHat = new Float64Array( n );
+    const grad = new Float64Array( p );
+
+    let prevLoss = Infinity;
+    let loss = 0;
+    let iterations = 0;
+
+    // ── Gradient descent loop ─────────────────────────────────────
+    for ( let iter = 0; iter < maxIter; iter += 1 ) {
+        iterations = iter + 1;
+        // ── Forward pass: z_i = wᵀx_i + b → pHat_i = σ(z_i) ─────
+        for ( let i = 0; i < n; i += 1 ) {
+            const row = X[ i ];
+            let z = intercept;
+            for ( let j = 0; j < p; j += 1 ) {
+                z += coefficients[ j ] * row[ j ];
+            }
+            pHat[ i ] = sigmoid( z );
+        }
+
+        // ── Loss: weighted cross-entropy + L2 penalty ─────────────
+        loss = 0;
+        for ( let i = 0; i < n; i += 1 ) {
+            const yi = y[ i ];
+            const pi = pHat[ i ];
+            const wi = w[ yi ];
+            // Sigmoid never returns exact 0 or 1, so log is safe.
+            loss -= wi * ( ( yi * Math.log( pi ) ) + ( ( 1 - yi ) * Math.log( 1 - pi ) ) );
+        }
+        loss /= n;
+        // L2 penalty on coefficients (not intercept).
+        let l2 = 0;
+        for ( let j = 0; j < p; j += 1 ) {
+            l2 += coefficients[ j ] * coefficients[ j ];
+        }
+        loss += ( lambda / 2 ) * l2;
+
+        // ── Convergence check (relative, with minIter guard) ──────
+        if ( iter >= minIter ) {
+            const relChange = Math.abs( prevLoss - loss ) / Math.max( 1, Math.abs( prevLoss ) );
+            if ( relChange < tol ) break;
+        }
+        prevLoss = loss;
+
+        // ── Gradient ──────────────────────────────────────────────
+        // Zero gradient accumulators.
+        for ( let j = 0; j < p; j += 1 ) grad[ j ] = 0;
+        let g0 = 0;
+
+        for ( let i = 0; i < n; i += 1 ) {
+            const row = X[ i ];
+            const err = pHat[ i ] - y[ i ];
+            const wi = w[ y[ i ] ];
+            const we = wi * err;
+            for ( let j = 0; j < p; j += 1 ) {
+                grad[ j ] += we * row[ j ];
+            }
+            g0 += we;
+        }
+        // Normalise and add L2 penalty to coefficient gradient.
+        for ( let j = 0; j < p; j += 1 ) {
+            grad[ j ] = ( grad[ j ] / n ) + ( lambda * coefficients[ j ] );
+        }
+        g0 /= n; // intercept: no regularization
+
+        // ── Update ────────────────────────────────────────────────
+        for ( let j = 0; j < p; j += 1 ) {
+            coefficients[ j ] -= alpha * grad[ j ];
+        }
+        intercept -= alpha * g0;
+    }
+
+    return {
+        coefficients: coefficients,
+        intercept: intercept,
+        loss: loss,
+        iterations: iterations
+    };
+}; // train()
+
+// ── Predict ───────────────────────────────────────────────────────
+
+/**
+ * Compute predicted probabilities for a feature matrix.
+ *
+ * @param {number[][]}    X            — Feature matrix (n × p).
+ * @param {Float64Array}  coefficients — Model weights.
+ * @param {number}        intercept    — Model bias.
+ * @returns {Float64Array} Probabilities, one per row.
+ */
+const predict = function ( X, coefficients, intercept ) {
+    const n = X.length;
+    const p = coefficients.length;
+    const probs = new Float64Array( n );
+
+    for ( let i = 0; i < n; i += 1 ) {
+        const row = X[ i ];
+        let z = intercept;
+        for ( let j = 0; j < p; j += 1 ) {
+            z += coefficients[ j ] * row[ j ];
+        }
+        probs[ i ] = sigmoid( z );
+    }
+
+    return probs;
+}; // predict()
+
+// ── Classify ──────────────────────────────────────────────────────
+
+/**
+ * Threshold probabilities into binary class labels.
+ *
+ * @param {Float64Array} probabilities — Output of predict().
+ * @param {number}       [threshold=0.5]
+ * @returns {Uint8Array} Binary labels (0 or 1).
+ */
+const classify = function ( probabilities, threshold ) {
+    const t = ( threshold === undefined ) ? 0.5 : threshold;
+    const n = probabilities.length;
+    const labels = new Uint8Array( n );
+
+    for ( let i = 0; i < n; i += 1 ) {
+        labels[ i ] = ( probabilities[ i ] >= t ) ? 1 : 0;
+    }
+
+    return labels;
+}; // classify()
+
+export { sigmoid, train, predict, classify };

package/src/tools/training/metrics.js

@@ -0,0 +1,126 @@
+// src/tools/training/metrics.js
+
+/**
+ * @fileoverview Binary classification evaluation metrics.
+ *
+ * Provides confusion-matrix computation, standard derived metrics
+ * (precision, recall, F1, specificity, FPR, accuracy), and a threshold
+ * sweep utility for ROC-style analysis.
+ *
+ * All inputs are validated for binary values (exactly 0 or 1) to prevent
+ * silent miscounts.
+ */
+
+import { validateBinaryArray } from './validate.js';
+
+// ── Confusion Matrix ──────────────────────────────────────────────
+
+/**
+ * Count true positives, false positives, false negatives, and true negatives.
+ *
+ * @param {ArrayLike<number>} predictions — Binary predictions (0 or 1).
+ * @param {ArrayLike<number>} labels      — Ground truth labels (0 or 1).
+ * @returns {{ tp: number, fp: number, fn: number, tn: number }}
+ */
+const confusionMatrix = function ( predictions, labels ) {
+    if ( predictions.length !== labels.length ) {
+        throw new Error( 'confusionMatrix: predictions and labels must have the same length.' );
+    }
+
+    validateBinaryArray( predictions, 'predictions', 'confusionMatrix' );
+    validateBinaryArray( labels, 'labels', 'confusionMatrix' );
+
+    const n = predictions.length;
+    let tp = 0;
+    let fp = 0;
+    let fn = 0;
+    let tn = 0;
+
+    for ( let i = 0; i < n; i += 1 ) {
+        const p = predictions[ i ];
+        const l = labels[ i ];
+        if ( p === 1 && l === 1 ) tp += 1;
+        else if ( p === 1 && l === 0 ) fp += 1;
+        else if ( p === 0 && l === 1 ) fn += 1;
+        else tn += 1;
+    }
+
+    return { tp, fp, fn, tn };
+}; // confusionMatrix()
+
+// ── Derived Metrics ───────────────────────────────────────────────
+
+/**
+ * Derive standard classification metrics from a confusion matrix.
+ *
+ * @param {{ tp: number, fp: number, fn: number, tn: number }} cm
+ * @returns {{ precision: number, recall: number, f1: number, specificity: number, fpr: number, accuracy: number }}
+ */
+const classificationMetrics = function ( cm ) {
+    const { tp, fp, fn, tn } = cm;
+    const total = tp + fp + fn + tn;
+
+    const precision = ( tp + fp ) > 0 ? tp / ( tp + fp ) : 0;
+    const recall = ( tp + fn ) > 0 ? tp / ( tp + fn ) : 0;
+    const f1 = ( precision + recall ) > 0 ?
+        ( 2 * precision * recall ) / ( precision + recall ) :
+        0;
+    const specificity = ( tn + fp ) > 0 ? tn / ( tn + fp ) : 0;
+    const fpr = ( tn + fp ) > 0 ? fp / ( tn + fp ) : 0;
+    const accuracy = total > 0 ? ( tp + tn ) / total : 0;
+
+    return { precision, recall, f1, specificity, fpr, accuracy };
+}; // classificationMetrics()
+
+// ── Threshold Sweep ───────────────────────────────────────────────
+
+/**
+ * Evaluate classification at multiple probability thresholds.
+ * Useful for ROC analysis and threshold selection.
+ *
+ * @param {Float64Array}  probabilities — Predicted probabilities.
+ * @param {ArrayLike<number>} labels    — Ground truth labels (0 or 1).
+ * @param {number[]}      thresholds    — Thresholds to evaluate.
+ * @returns {Array<{ threshold: number, tp: number, fp: number, fn: number, tn: number, precision: number, recall: number, f1: number, specificity: number, fpr: number }>}
+ */
+const sweepThresholds = function ( probabilities, labels, thresholds ) {
+    if ( probabilities.length !== labels.length ) {
+        throw new Error( 'sweepThresholds: probabilities and labels must have the same length.' );
+    }
+
+    validateBinaryArray( labels, 'labels', 'sweepThresholds' );
+
+    const n = probabilities.length;
+    const results = new Array( thresholds.length );
+
+    for ( let t = 0; t < thresholds.length; t += 1 ) {
+        const thresh = thresholds[ t ];
+        let tp = 0;
+        let fp = 0;
+        let fn = 0;
+        let tn = 0;
+
+        for ( let i = 0; i < n; i += 1 ) {
+            const pred = ( probabilities[ i ] >= thresh ) ? 1 : 0;
+            const label = labels[ i ];
+            if ( pred === 1 && label === 1 ) tp += 1;
+            else if ( pred === 1 && label === 0 ) fp += 1;
+            else if ( pred === 0 && label === 1 ) fn += 1;
+            else tn += 1;
+        }
+
+        const precision = ( tp + fp ) > 0 ? tp / ( tp + fp ) : 0;
+        const recall = ( tp + fn ) > 0 ? tp / ( tp + fn ) : 0;
+        const f1 = ( precision + recall ) > 0 ?
+            ( 2 * precision * recall ) / ( precision + recall ) :
+            0;
+        const specificity = ( tn + fp ) > 0 ? tn / ( tn + fp ) : 0;
+        const fpr = ( tn + fp ) > 0 ? fp / ( tn + fp ) : 0;
+
+        results[ t ] = { threshold: thresh, tp, fp, fn, tn, precision, recall, f1, specificity, fpr };
+    }
+
+    return results;
+}; // sweepThresholds()
+
+export { confusionMatrix, classificationMetrics, sweepThresholds };