Class OnlineICA
Online Independent Component Analysis (ICA) using incremental FastICA learning.
JSON configuration
Use these block entries inside a pipeline configuration. Input names must match other blocks in that pipeline; device addresses and file paths must match your setup.
JSON configuration:
{
"EMG_ICA": {
"Type": "OnlineICA",
"Inputs": [ "SlidingWindow1" ],
"Params": [ 3, 0.1, 50, 1000, 0, 500, 1, 0, 0.005 ],
"DesiredRate": 1000,
"Path": "output/emg_ica"
}
}
Params:
| Index | Description |
|---|---|
| 0 | k (int) — Number of independent components to extract. Default: 2. |
| 1 | eta0 (double) — Initial learning rate η₀. Range: 0.01–0.2. Default: 0.1. |
| 2 | reorthEvery (int) — Orthonormalization frequency in samples. Default: 50. |
| 3 | minStableCount (int) — Minimum samples before model is stable. Default: 1000. |
| 4 | contrastFunction (double) — Contrast function: 0 = LogCosh, 1 = Exp, 2 = Cube. Default: 0. |
| 5 | warmupSamples (int) — Warm-up samples (whitening only). Set 0 to disable. Default: 500. |
| 6 | freezeWhiteningAfterWarmup (int) — 1 = freeze whitening after warm-up, 0 = keep updating. Default: 1. |
| 7 | adaptiveWhitening (int) — 1 = enable adaptive whitening for non-stationary signals, 0 = off. Default: 0. |
| 8 | covarianceDecay (double) — EWMA decay for adaptive covariance. Range: 0.0001–0.5. Default: 0.005. |
Path: Optional. If provided, CSV logs of projected outputs are written to this directory.
How Type, Inputs and Params work · Block catalogue and parameter reference
Implements
Inherited Members
Namespace: MOSAIC.Models.Analytics
Assembly: MOSAIC.dll
Syntax
public class OnlineICA : BaseBlock, INotifyPropertyChanged, INotifyPropertyChanging, ISubscriber, IPublisher, IBaseBlockProps, IJsonExportable, IDisposable, IAsyncDisposable
Remarks
Overview:
ICA is a computational technique for separating a multivariate signal into additive,
statistically independent non-Gaussian source signals. This implementation provides
real-time blind source separation using an online (incremental) learning approach.
Mathematical Model:
ICA assumes the observed data follows the linear mixing model:
x = A · s
where:
xis the observed d-dimensional signal vectorsis the k-dimensional vector of independent source signalsAis the unknown d×k mixing matrix
The goal is to find the unmixing matrix W such that:
y = W · x ≈ s
where y contains the estimated independent components.
Algorithm Pipeline:
- Centering: Remove mean: x_centered = x - μ
- Whitening: Decorrelate and normalize variance: z = W_white · x_centered
- ICA Rotation: Find rotation maximizing independence: y = W · z
Whitening (PCA-based):
Whitening transforms data to have identity covariance. Given covariance matrix C with
eigendecomposition C = V·D·V^T, the whitening matrix is:
W_white = D^(-1/2) · V^T
This ensures E[z·z^T] = I, simplifying the ICA optimization to finding an orthogonal rotation.
FastICA Update Rule:
The natural gradient update for the unmixing matrix W is:
w_i ← w_i + η · (z · g(w_i^T · z) - g'(w_i^T · z) · w_i)
where:
g(y)is the derivative of the contrast function G(y)g'(y)is the second derivative of G(y)ηis the learning rate
Contrast Functions:
The contrast function G(y) measures non-Gaussianity. Available options:
| Function | G(y), g(y), g'(y) |
|---|---|
| LogCosh (default, robust) | G(y) = log(cosh(y)), g(y) = tanh(y), g'(y) = 1 - tanh²(y) |
| Exp (super-Gaussian) | G(y) = -exp(-y²/2), g(y) = y·exp(-y²/2), g'(y) = (1-y²)·exp(-y²/2) |
| Cube (sub-Gaussian, fast) | G(y) = y⁴/4, g(y) = y³, g'(y) = 3y² |
Online Covariance Estimation:
Uses Welford's numerically stable algorithm for incremental mean and covariance:
δ = x - μ_old
μ_new = μ_old + δ/n
δ' = x - μ_new
M2 = M2 + outer(δ, δ')
C = M2 / (n-1)
Independence Metrics:
- Excess Kurtosis: κ = E[y⁴] - 3. Zero for Gaussian, positive for super-Gaussian (heavy tails), negative for sub-Gaussian (light tails).
- Negentropy: J(y) ≈ [E{G(y)} - E{G(ν)}]² where ν ~ N(0,1). Always non-negative, zero only for Gaussian distributions.
Numerical Stability Features:
- Symmetric orthonormalization: W ← W·(W·W^T)^(-1/2)
- Learning rate warm-up and decay schedule
- Gradient clipping to prevent exploding updates
- Eigenvalue validation before whitening updates
- Sign correction for component stability
References:
- Hyvärinen, A. (1999). Fast and Robust Fixed-Point Algorithms for Independent Component Analysis. IEEE Trans. Neural Networks.
- Hyvärinen, A., Karhunen, J., Oja, E. (2001). Independent Component Analysis. Wiley.
- Welford, B.P. (1962). Note on a Method for Calculating Corrected Sums of Squares and Products. Technometrics.
Constructors
OnlineICA(string, double, int, double, int, int, double, int, bool, bool, double)
Initializes a new instance of the OnlineICA class.
Declaration
public OnlineICA(string name, double desiredRate = 0, int k = 2, double eta0 = 0.1, int reorthEvery = 50, int minStableCount = 1000, double contrastFunction = 0, int warmupSamples = 500, bool freezeWhiteningAfterWarmup = true, bool adaptiveWhitening = false, double covarianceDecay = 0.005)
Parameters
| Type | Name | Description |
|---|---|---|
| string | name | Unique identifier for this processing block. |
| double | desiredRate | Target processing rate in Hz (0 = unlimited). |
| int | k | Number of independent components to extract. For complete source separation, use k = d (input dimension). For EMG: typically 2-4 components. |
| double | eta0 | Initial learning rate η₀ ∈ (0, 1]. Typical values: 0.01-0.2. Higher values converge faster but may be unstable. |
| int | reorthEvery | Orthonormalization frequency. W is orthonormalized every N samples. Lower values improve stability but increase computation. Typical: 10-100. |
| int | minStableCount | Minimum samples before model is considered stable. Sign correction only activates after this threshold. Typical: 500-2000. |
| double | contrastFunction | Contrast function selector:
|
| int | warmupSamples | Number of samples for warm-up phase. During warm-up, only whitening is estimated; ICA rotation learning begins after. Typical: 200-1000. Set to 0 to disable warm-up. |
| bool | freezeWhiteningAfterWarmup | If true, whitening matrix is frozen after warm-up phase. Set to false for adaptive whitening with non-stationary signals. |
| bool | adaptiveWhitening | If true, enables adaptive whitening for non-stationary signals (EMG, ultrasound). Uses exponentially weighted covariance and smooth W transformation. |
| double | covarianceDecay | Decay factor for exponentially weighted covariance in adaptive mode. Range: 0.001-0.1. Lower = more stable, higher = faster adaptation. Typical for EMG at 1kHz: 0.001-0.01. |
Examples
// Setup for EMG source separation with adaptive whitening
var ica = new OnlineICA(
name: "EMG_ICA",
k: 3,
eta0: 0.1,
warmupSamples: 500,
freezeWhiteningAfterWarmup: false,
adaptiveWhitening: true,
covarianceDecay: 0.005
);
Exceptions
| Type | Condition |
|---|---|
| ArgumentOutOfRangeException | Thrown when |
Fields
_C
Covariance matrix estimate C (d×d).
Declaration
private Matrix<double> _C
Field Value
| Type | Description |
|---|---|
| Matrix<double> |
_M2
Sum of squared deviations M₂ for Welford's algorithm. Used to compute covariance: C = M₂ / (n-1).
Declaration
private Matrix<double> _M2
Field Value
| Type | Description |
|---|---|
| Matrix<double> |
_W
ICA unmixing/rotation matrix W (k×k). Operates in whitened space: y = W · z.
Declaration
private Matrix<double> _W
Field Value
| Type | Description |
|---|---|
| Matrix<double> |
_adaptiveWhitening
Adaptive whitening mode for non-stationary signals (EMG, ultrasound).
Declaration
private readonly bool _adaptiveWhitening
Field Value
| Type | Description |
|---|---|
| bool |
_baselineCov
Baseline covariance from warm-up for drift detection.
Declaration
private Matrix<double>? _baselineCov
Field Value
| Type | Description |
|---|---|
| Matrix<double> |
_contrastFunction
Contrast function selector: 0=logcosh, 1=exp, 2=cube.
Declaration
private readonly double _contrastFunction
Field Value
| Type | Description |
|---|---|
| double |
_covarianceDecay
Exponential decay factor for adaptive covariance (0 = no decay, 1 = instant).
Declaration
private readonly double _covarianceDecay
Field Value
| Type | Description |
|---|---|
| double |
_d
Input dimensionality (set on first sample).
Declaration
private int _d
Field Value
| Type | Description |
|---|---|
| int |
_dewhiteningMatrix
Dewhitening matrix (d×k) for inverse transformation. Computed as V · D^(1/2) using top k eigenvectors.
Declaration
private Matrix<double> _dewhiteningMatrix
Field Value
| Type | Description |
|---|---|
| Matrix<double> |
_driftMetric
Current drift metric (Frobenius norm of covariance change).
Declaration
private double _driftMetric
Field Value
| Type | Description |
|---|---|
| double |
_driftThreshold
Threshold for triggering adaptation.
Declaration
private readonly double _driftThreshold
Field Value
| Type | Description |
|---|---|
| double |
_emaAlpha
EMA smoothing factor α (0 < α < 1).
Declaration
private readonly double _emaAlpha
Field Value
| Type | Description |
|---|---|
| double |
_eta0
Initial learning rate η₀.
Declaration
private readonly double _eta0
Field Value
| Type | Description |
|---|---|
| double |
_ewmaCov
Exponentially weighted covariance for drift detection.
Declaration
private Matrix<double>? _ewmaCov
Field Value
| Type | Description |
|---|---|
| Matrix<double> |
_freezeWhiteningAfterWarmup
Whether whitening is frozen after warm-up.
Declaration
private readonly bool _freezeWhiteningAfterWarmup
Field Value
| Type | Description |
|---|---|
| bool |
_gEma
EMA of G(y) for proper negentropy calculation.
Declaration
private Vector<double> _gEma
Field Value
| Type | Description |
|---|---|
| Vector<double> |
_gPrimeY
Preallocated contrast derivative values g'(y).
Declaration
private Vector<double>? _gPrimeY
Field Value
| Type | Description |
|---|---|
| Vector<double> |
_gY
Preallocated contrast function values g(y).
Declaration
private Vector<double>? _gY
Field Value
| Type | Description |
|---|---|
| Vector<double> |
_invalidWhiteningRate
Declaration
private LogRate _invalidWhiteningRate
Field Value
| Type | Description |
|---|---|
| LogRate |
_isStable
Whether model has reached stable state.
Declaration
private bool _isStable
Field Value
| Type | Description |
|---|---|
| bool |
_k
Number of independent components to extract.
Declaration
private readonly int _k
Field Value
| Type | Description |
|---|---|
| int |
_kurtosisEma
Exponential moving average of excess kurtosis per component.
Declaration
private Vector<double> _kurtosisEma
Field Value
| Type | Description |
|---|---|
| Vector<double> |
_mean
Running mean estimate μ (d-dimensional).
Declaration
private Vector<double> _mean
Field Value
| Type | Description |
|---|---|
| Vector<double> |
_minStableCount
Minimum samples before considering model stable.
Declaration
private readonly int _minStableCount
Field Value
| Type | Description |
|---|---|
| int |
_n
Total number of processed samples.
Declaration
private long _n
Field Value
| Type | Description |
|---|---|
| long |
_negentropyEma
Exponential moving average of negentropy per component.
Declaration
private Vector<double> _negentropyEma
Field Value
| Type | Description |
|---|---|
| Vector<double> |
_prevICs
Previous IC directions for sign correction (generic for any k).
Declaration
private Vector<double>[]? _prevICs
Field Value
| Type | Description |
|---|---|
| Vector<double>[] |
_prevWhiteningMatrix
Previous whitening matrix for detecting significant changes.
Declaration
private Matrix<double>? _prevWhiteningMatrix
Field Value
| Type | Description |
|---|---|
| Matrix<double> |
_reorthEvery
Frequency of orthonormalization (every N samples).
Declaration
private readonly int _reorthEvery
Field Value
| Type | Description |
|---|---|
| int |
_smallEigenvalueRate
Throttles for the whitening diagnostics below. They are reached from Process() on the data thread, so an unguarded failure would report itself at sample rate.
Declaration
private LogRate _smallEigenvalueRate
Field Value
| Type | Description |
|---|---|
| LogRate |
_warmupComplete
Whether warm-up phase is complete.
Declaration
private bool _warmupComplete
Field Value
| Type | Description |
|---|---|
| bool |
_warmupSamples
Number of samples for warm-up phase (whitening estimation only).
Declaration
private readonly int _warmupSamples
Field Value
| Type | Description |
|---|---|
| int |
_whiteningErrorRate
Declaration
private LogRate _whiteningErrorRate
Field Value
| Type | Description |
|---|---|
| LogRate |
_whiteningMatrix
Whitening matrix W_white (k×d). Transforms centered data to whitened space: z = W_white · (x - μ). Computed as D^(-1/2) · V^T from eigendecomposition of C.
Declaration
private Matrix<double> _whiteningMatrix
Field Value
| Type | Description |
|---|---|
| Matrix<double> |
_xWhitened
Preallocated whitened input vector.
Declaration
private Vector<double>? _xWhitened
Field Value
| Type | Description |
|---|---|
| Vector<double> |
_y
Preallocated output (independent components) vector.
Declaration
private Vector<double>? _y
Field Value
| Type | Description |
|---|---|
| Vector<double> |
_y2Ema
EMA of y^2 for proper kurtosis calculation.
Declaration
private Vector<double> _y2Ema
Field Value
| Type | Description |
|---|---|
| Vector<double> |
_y4Ema
EMA of y^4 for proper kurtosis calculation.
Declaration
private Vector<double> _y4Ema
Field Value
| Type | Description |
|---|---|
| Vector<double> |
Properties
ComponentCount
Gets the number of independent components (k).
Declaration
public int ComponentCount { get; }
Property Value
| Type | Description |
|---|---|
| int | The dimensionality of the output space. |
Covariance
Gets the current covariance matrix estimate C.
Declaration
public Matrix<double> Covariance { get; }
Property Value
| Type | Description |
|---|---|
| Matrix<double> | The d×d sample covariance matrix. |
Remarks
Computed using Welford's numerically stable algorithm:
C = M₂ / (n - 1)
where M₂ accumulates outer products of deviations.
Includes small diagonal regularization (1e-8) for numerical stability.
DriftMetric
Gets the current signal drift metric.
Declaration
public double DriftMetric { get; }
Property Value
| Type | Description |
|---|---|
| double | Relative drift from baseline (0 = no drift, >0.2 = significant drift). |
Remarks
Measures how much the signal statistics have drifted from the baseline established during warm-up. Computed as relative Frobenius norm:
drift = ||C_current - C_baseline||_F / ||C_baseline||_F
Useful for EMG/ultrasound applications to detect:
- Electrode movement or contact changes
- Muscle fatigue affecting signal characteristics
- Need for recalibration
DumpFilePrefix
Recordings from this block are named <block>_projections.csv.
Declaration
protected override string DumpFilePrefix { get; }
Property Value
| Type | Description |
|---|---|
| string |
Overrides
IsStable
Gets whether the model has reached a stable state.
Declaration
public bool IsStable { get; }
Property Value
| Type | Description |
|---|---|
| bool |
|
Remarks
The model is considered stable after processing minStableCount
samples. Sign correction is only applied after stability is reached.
Kurtosis
Gets the estimated excess kurtosis for each independent component.
Declaration
public Vector<double> Kurtosis { get; }
Property Value
| Type | Description |
|---|---|
| Vector<double> | Vector of excess kurtosis values, one per component. |
Remarks
Excess kurtosis is properly computed as:
κ = E[y⁴] / E[y²]² - 3
This normalization ensures scale-invariance.
Interpretation:
- κ = 0: Gaussian (mesokurtic)
- κ > 0: Super-Gaussian / leptokurtic (heavy tails, e.g., Laplace)
- κ < 0: Sub-Gaussian / platykurtic (light tails, e.g., uniform)
Values are smoothed using exponential moving average.
Mean
Gets the current mean estimate μ.
Declaration
public Vector<double> Mean { get; }
Property Value
| Type | Description |
|---|---|
| Vector<double> | The d-dimensional mean vector. |
Remarks
Updated online using Welford's algorithm: μ_new = μ_old + (x - μ_old) / n.
Negentropy
Gets the estimated negentropy for each independent component.
Declaration
public Vector<double> Negentropy { get; }
Property Value
| Type | Description |
|---|---|
| Vector<double> | Vector of negentropy values, one per component. |
Remarks
Negentropy measures the distance from Gaussianity:
J(y) ≈ [E{G(y)} - E{G(ν)}]²
where ν ~ N(0,1) is a standard normal reference.
Properties:
- J(y) ≥ 0 always
- J(y) = 0 if and only if y is Gaussian
- Higher values indicate more non-Gaussian (more independent) components
Values are smoothed using exponential moving average.
SampleCount
Gets the total number of samples processed.
Declaration
public long SampleCount { get; }
Property Value
| Type | Description |
|---|---|
| long | Sample count since initialization or last reset. |
UnmixingMatrix
Gets the full unmixing matrix A⁻¹ = W · W_white (k×d).
Declaration
public Matrix<double> UnmixingMatrix { get; }
Property Value
| Type | Description |
|---|---|
| Matrix<double> | The combined whitening and ICA rotation matrix. |
Remarks
This matrix directly transforms centered input to independent components:
y = UnmixingMatrix · (x - Mean)
WarmupComplete
Gets whether the warm-up phase is complete.
Declaration
public bool WarmupComplete { get; }
Property Value
| Type | Description |
|---|---|
| bool |
|
Remarks
During warm-up, only mean/covariance/whitening are estimated. ICA rotation (W) learning begins after warm-up completes.
WhiteningMatrix
Gets the whitening matrix W_white (k×d).
Declaration
public Matrix<double> WhiteningMatrix { get; }
Property Value
| Type | Description |
|---|---|
| Matrix<double> | The whitening transformation matrix. |
Remarks
Transforms centered data to have identity covariance in k-dimensional space. Computed from eigendecomposition of covariance: W_white = D^(-1/2) · V^T.
Methods
ComputeBasisTransform(Matrix<double>, Matrix<double>)
Computes the transformation matrix T = W_old · pinv(W_new) for basis change.
Declaration
private Matrix<double> ComputeBasisTransform(Matrix<double> Wold, Matrix<double> Wnew)
Parameters
| Type | Name | Description |
|---|---|---|
| Matrix<double> | Wold | Old whitening matrix (k×d). |
| Matrix<double> | Wnew | New whitening matrix (k×d). |
Returns
| Type | Description |
|---|---|
| Matrix<double> | Transformation matrix T (k×k). |
Remarks
For k×d matrices where k ≤ d:
pinv(W) = W^T · (W · W^T)^(-1)
This gives T = W_old · W_new^T · (W_new · W_new^T)^(-1)
ComputeContrastGradient(Vector<double>, Vector<double>, Vector<double>)
Computes the contrast function derivatives g(y) and g'(y) for all components.
Declaration
private void ComputeContrastGradient(Vector<double> y, Vector<double> g, Vector<double> gPrime)
Parameters
| Type | Name | Description |
|---|---|---|
| Vector<double> | y | Independent component values. |
| Vector<double> | g | Output: g(y) = G'(y) values. |
| Vector<double> | gPrime | Output: g'(y) = G''(y) values. |
Remarks
Contrast Functions:
| Type | G(y), g(y), g'(y) |
|---|---|
| LogCosh |
G(y) = log(cosh(y)) g(y) = tanh(y) g'(y) = 1 - tanh²(y) = sech²(y) |
| Exp |
G(y) = -exp(-y²/2) g(y) = y · exp(-y²/2) g'(y) = (1 - y²) · exp(-y²/2) |
| Cube |
G(y) = y⁴/4 g(y) = y³ g'(y) = 3y² |
ConfigureInput(IServiceProvider, JsonModel)
Creates an OnlineICA instance from JSON configuration.
Declaration
public static OnlineICA ConfigureInput(IServiceProvider sp, JsonModel m)
Parameters
| Type | Name | Description |
|---|---|---|
| IServiceProvider | sp | Service provider for dependency injection. |
| JsonModel | m | JSON model containing configuration. Expected Params order: [0] k (int), [1] eta0 (double), [2] reorthEvery (int), [3] minStableCount (int), [4] contrastFunction (double), [5] warmupSamples (int), [6] freezeWhiteningAfterWarmup (0/1), [7] adaptiveWhitening (0/1), [8] covarianceDecay (double). |
Returns
| Type | Description |
|---|---|
| OnlineICA | Configured OnlineICA instance. |
Examples
JSON configuration for EMG with adaptive whitening:
{
"Name": "EMG_ICA",
"DesiredRate": 1000,
"Params": [3, 0.1, 50, 1000, 0, 500, 0, 1, 0.005],
"Path": "output/emg_ica"
}
CorrectICSigns()
Corrects the sign of independent components for temporal consistency.
Declaration
private void CorrectICSigns()
Remarks
ICA has inherent sign ambiguity: if w is a valid unmixing vector, so is -w. This can cause sign flips between updates, making visualization difficult.
This method tracks the previous direction of each component and flips the sign if the dot product with the previous direction is negative. Only active after IsStable becomes true.
Generic implementation works for any k (number of components).
Dispose()
Releases all resources used by this instance.
Declaration
public override void Dispose()
Overrides
EnsureInit(int)
Ensures all internal state is properly initialized for the given input dimension.
Declaration
private void EnsureInit(int d)
Parameters
| Type | Name | Description |
|---|---|---|
| int | d | Input vector dimensionality. |
Remarks
Called automatically on first sample or when input dimension changes. Reinitializes all matrices and resets sample counter.
Exceptions
| Type | Condition |
|---|---|
| ArgumentOutOfRangeException | Thrown when d ≤ 0 or d < k. |
GetJsonParams()
Exports the live hyper-parameters in the exact order ConfigureInput(IServiceProvider, JsonModel) reads them:
[0] k, [1] eta0, [2] reorthEvery, [3] minStableCount, [4] contrastFunction,
[5] warmupSamples, [6] freezeWhiteningAfterWarmup, [7] adaptiveWhitening, [8] covarianceDecay.
Inherited unchanged by SupervisedICA, whose parameter layout is identical.
Declaration
protected override IReadOnlyList<object>? GetJsonParams()
Returns
| Type | Description |
|---|---|
| IReadOnlyList<object> | The values for Params. |
Overrides
InverseTransform(Vector<double>)
Reconstructs an approximation of the original signal from independent components.
Declaration
public Vector<double> InverseTransform(Vector<double> y)
Parameters
| Type | Name | Description |
|---|---|---|
| Vector<double> | y | Independent components vector (k-dimensional). |
Returns
| Type | Description |
|---|---|
| Vector<double> | Reconstructed observation vector (d-dimensional). |
Remarks
Applies the inverse transformation:
x ≈ W_dewhite · W^T · y + μ
Note: This is an approximate inverse. If k < d, information is lost and perfect reconstruction is not possible.
Examples
var components = ica.Transform(sample);
// Modify components (e.g., remove artifact)
components[0] = 0;
var cleaned = ica.InverseTransform(components);
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | Thrown when ICA has not been initialized. |
| ArgumentNullException | Thrown when y is null. |
| InvalidOperationException | Thrown when y dimension doesn't match k. |
OnReceive(object, object)
Handles incoming data from the observable pipeline.
Declaration
protected override void OnReceive(object sender, object data)
Parameters
| Type | Name | Description |
|---|---|---|
| object | sender | The source of the data. |
| object | data | Input data. Supported types:
|
Overrides
Remarks
For matrix input, each row is processed sequentially as an independent observation. Unsupported data types are logged and ignored.
Orthonormalize(Matrix<double>)
Orthonormalizes the unmixing matrix W using symmetric decorrelation.
Declaration
private static void Orthonormalize(Matrix<double> W)
Parameters
| Type | Name | Description |
|---|---|---|
| Matrix<double> | W | The matrix to orthonormalize (modified in place). |
Remarks
Uses symmetric orthonormalization:
W ← (W · W^T)^(-1/2) · W
This is computed via eigendecomposition:
W·W^T = V · D · V^T
(W·W^T)^(-1/2) = V · D^(-1/2) · V^T
Symmetric orthonormalization is preferred over Gram-Schmidt because it treats all directions equally, avoiding accumulation of errors in later components. Falls back to Gram-Schmidt if eigendecomposition fails.
OrthonormalizeGramSchmidt(Matrix<double>)
Orthonormalizes matrix rows using the Gram-Schmidt process (fallback method).
Declaration
private static void OrthonormalizeGramSchmidt(Matrix<double> W)
Parameters
| Type | Name | Description |
|---|---|---|
| Matrix<double> | W | The matrix to orthonormalize (modified in place). |
Remarks
For each row w_i:
w_i ← w_i - Σ_{j<i} (w_i · w_j) · w_j
w_i ← w_i / ||w_i||
Less numerically stable than symmetric orthonormalization for ICA, but useful as a fallback when eigendecomposition fails.
Process(Vector<double>)
Processes a single input vector through the online ICA pipeline.
Declaration
protected virtual void Process(Vector<double> x)
Parameters
| Type | Name | Description |
|---|---|---|
| Vector<double> | x | Input observation vector (d-dimensional). |
Remarks
Processing Pipeline:
Phase 1 - Warm-up (samples 1 to warmupSamples):
- Estimate mean and covariance only
- At end of warm-up: compute initial whitening matrix
- W remains identity during warm-up
Phase 2 - ICA Learning (after warm-up):
- Update online mean/covariance estimates
- Center and whiten input
- Apply ICA rotation: y = W · z
- Update independence metrics
- Apply FastICA natural gradient update to W
- Periodic: Orthonormalize W, correct signs
- Optional: Update whitening (with W reset if significant change)
Exceptions
| Type | Condition |
|---|---|
| ArgumentNullException | Thrown when x is null. |
PublishProjection(Vector<double>)
Publishes the independent components to downstream subscribers.
Declaration
protected virtual void PublishProjection(Vector<double> projection)
Parameters
| Type | Name | Description |
|---|---|---|
| Vector<double> | projection | The k-dimensional independent component vector. |
Remarks
Protected virtual to allow interception or modification in derived classes.
Reset()
Resets all learned parameters to initial state.
Declaration
public void Reset()
Remarks
Clears:
- Mean and covariance estimates
- Whitening and unmixing matrices
- Independence metrics
- Sample counter and stability flag
After reset, the next Process(Vector<double>) call will reinitialize all state based on the input dimension.
StableLogCosh(double)
Numerically stable computation of log(cosh(y)).
Declaration
private static double StableLogCosh(double y)
Parameters
| Type | Name | Description |
|---|---|---|
| double | y | Input value. |
Returns
| Type | Description |
|---|---|
| double | log(cosh(y)) without overflow for large |y|. |
Remarks
For large |y|, cosh(y) ≈ exp(|y|)/2, so log(cosh(y)) ≈ |y| - log(2). We use the identity:
log(cosh(y)) = |y| + log(1 + exp(-2|y|)) - log(2)
which is numerically stable for all y.
Transform(Vector<double>)
Transforms a single observation to independent components using the learned unmixing matrix.
Declaration
public Vector<double> Transform(Vector<double> x)
Parameters
| Type | Name | Description |
|---|---|---|
| Vector<double> | x | Input observation vector (d-dimensional). |
Returns
| Type | Description |
|---|---|
| Vector<double> | Independent components vector (k-dimensional). |
Remarks
Applies the transformation:
y = W · W_white · (x - μ)
Unlike Process(Vector<double>), this method does not update any internal state. Use for transforming new data after training.
Examples
// After processing training data...
var newSample = DenseVector.OfArray(new[] { 1.0, 2.0, 3.0 });
var components = ica.Transform(newSample);
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | Thrown when ICA has not been initialized (no data processed yet). |
| ArgumentNullException | Thrown when x is null. |
| InvalidOperationException | Thrown when x dimension doesn't match expected input dimension. |
TryDouble(IReadOnlyList<object>?, int, double)
Attempts to parse a double from a parameter list.
Declaration
private static double TryDouble(IReadOnlyList<object>? p, int idx, double def)
Parameters
| Type | Name | Description |
|---|---|---|
| IReadOnlyList<object> | p | Parameter list. |
| int | idx | Index to read. |
| double | def | Default value if parsing fails. |
Returns
| Type | Description |
|---|---|
| double | Parsed double or default. |
TryInt(IReadOnlyList<object>?, int, int)
Attempts to parse an integer from a parameter list.
Declaration
private static int TryInt(IReadOnlyList<object>? p, int idx, int def)
Parameters
| Type | Name | Description |
|---|---|---|
| IReadOnlyList<object> | p | Parameter list. |
| int | idx | Index to read. |
| int | def | Default value if parsing fails. |
Returns
| Type | Description |
|---|---|
| int | Parsed integer or default. |
UpdateKurtosisEstimate(Vector<double>)
Updates the kurtosis estimate using exponential moving average.
Declaration
private void UpdateKurtosisEstimate(Vector<double> y)
Parameters
| Type | Name | Description |
|---|---|---|
| Vector<double> | y | Current independent component values. |
Remarks
Properly normalized excess kurtosis:
κ = E[y⁴] / E[y²]² - 3
This formula is scale-invariant, unlike the simpler E[y⁴] - 3.
We track E[y²] and E[y⁴] separately via EMA, then compute κ on demand in the Kurtosis property.
UpdateNegentropyEstimate(Vector<double>)
Updates the negentropy estimate using exponential moving average.
Declaration
private void UpdateNegentropyEstimate(Vector<double> y)
Parameters
| Type | Name | Description |
|---|---|---|
| Vector<double> | y | Current independent component values. |
Remarks
Correct negentropy approximation:
J(y) ≈ [E{G(y)} - E{G(ν)}]²
where ν ~ N(0,1).
We track G_ema = E[G(y)] via EMA, then compute J = (G_ema - c)². This is more stable than tracking (G-c)² directly.
Gaussian reference values E{G(ν)}:
- LogCosh: 0.3746
- Exp: -1/√2 ≈ -0.7071
- Cube: E[ν⁴]/4 = 3/4 = 0.75
UpdateWhiteningAdaptive()
Updates the whitening matrix adaptively for non-stationary signals.
Declaration
private void UpdateWhiteningAdaptive()
Remarks
Designed for EMG/ultrasound applications where signal statistics drift slowly.
Key insight: When whitening changes from W_old to W_new, we must transform W to maintain the same overall unmixing:
y = W · z_old = W · W_white_old · x
y = W_new · z_new = W_new · W_white_new · x
Therefore: W_new = W · W_white_old · pinv(W_white_new)
For k = d (full separation), pinv = inverse. For k < d, we use pseudoinverse.
UpdateWhiteningMatrix()
Updates the whitening matrix using eigendecomposition of the covariance matrix.
Declaration
private void UpdateWhiteningMatrix()
Remarks
Given covariance C with eigendecomposition C = V·D·V^T:
W_white = D^(-1/2) · V^T (whitening)
W_dewhite = V · D^(1/2) (dewhitening)
Only the top k eigenvectors (by eigenvalue magnitude) are used, providing dimensionality reduction combined with whitening.
Includes validation checks:
- Minimum eigenvalue threshold (1e-10)
- NaN/Inf detection in resulting matrix
UpdateWhiteningMatrixWithConsistency()
Updates the whitening matrix with consistency handling for W.
Declaration
private void UpdateWhiteningMatrixWithConsistency()
Remarks
When the whitening matrix changes significantly, the old W is no longer valid because it was learned in a different whitened space. This method handles two strategies:
- Transform W: W_new = W_old · W_white_old · W_white_new^(-1) Preserves learned rotations but may accumulate numerical errors.
- Reset W: If change is too large, reset W = I and restart learning. More robust but loses learned information.