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:

IndexDescription
0k (int) — Number of independent components to extract. Default: 2.
1eta0 (double) — Initial learning rate η₀. Range: 0.01–0.2. Default: 0.1.
2reorthEvery (int) — Orthonormalization frequency in samples. Default: 50.
3minStableCount (int) — Minimum samples before model is stable. Default: 1000.
4contrastFunction (double) — Contrast function: 0 = LogCosh, 1 = Exp, 2 = Cube. Default: 0.
5warmupSamples (int) — Warm-up samples (whitening only). Set 0 to disable. Default: 500.
6freezeWhiteningAfterWarmup (int) — 1 = freeze whitening after warm-up, 0 = keep updating. Default: 1.
7adaptiveWhitening (int) — 1 = enable adaptive whitening for non-stationary signals, 0 = off. Default: 0.
8covarianceDecay (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

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:

  • x is the observed d-dimensional signal vector
  • s is the k-dimensional vector of independent source signals
  • A is 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:

  1. Centering: Remove mean: x_centered = x - μ
  2. Whitening: Decorrelate and normalize variance: z = W_white · x_centered
  3. 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:

FunctionG(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:

  • 0 = LogCosh (default, robust for most signals including EMG)
  • 1 = Exp (good for super-Gaussian sources)
  • 2 = Cube (fast, good for sub-Gaussian sources)
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 k is less than 1.

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
BaseBlock.DumpFilePrefix

IsStable

Gets whether the model has reached a stable state.

Declaration
public bool IsStable { get; }
Property Value
Type Description
bool

true if stable; otherwise, false.

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

true if warm-up is complete; otherwise, false.

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:

TypeG(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
BaseBlock.Dispose()

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
BaseBlock.GetJsonParams()

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:

  • MathNet.Numerics.LinearAlgebra.Vector<T>: Single observation vector
  • MathNet.Numerics.LinearAlgebra.Matrix<T>: Multiple observations (one per row)
Overrides
BaseBlock.OnReceive(object, object)
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):

  1. Update online mean/covariance estimates
  2. Center and whiten input
  3. Apply ICA rotation: y = W · z
  4. Update independence metrics
  5. Apply FastICA natural gradient update to W
  6. Periodic: Orthonormalize W, correct signs
  7. 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.

Implements

INotifyPropertyChanged
INotifyPropertyChanging
ISubscriber
IPublisher
IBaseBlockProps
IJsonExportable
IDisposable
IAsyncDisposable

Search documentation

Start typing to search the documentation.