Class OnlinePCA

Online Principal Component Analysis using incremental (streaming) Oja's learning rule.

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:

{
  "MyPCA": {
    "Type": "OnlinePCA",
    "Inputs": [ "SlidingWindow1" ],
    "Params": [ 2, 0.2, 100, 500 ],
    "DesiredRate": 100,
    "Path": "output/pca_log"
  }
}

Params:

IndexDescription
0k (int) — Number of principal components (2 or 3). Default: 2.
1eta0 (double) — Initial learning rate η₀. Default: 0.2.
2reorthEvery (int) — QR orthonormalisation frequency in samples. Default: 100.
3minStableCount (int) — Minimum samples before model is stable. Default: 500.

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 OnlinePCA : BaseBlock, INotifyPropertyChanged, INotifyPropertyChanging, ISubscriber, IPublisher, IBaseBlockProps, IJsonExportable, IDisposable, IAsyncDisposable
Remarks

Overview: PCA finds orthogonal directions of maximum variance in the input data. This implementation learns the top k principal components incrementally, one sample at a time, making it suitable for real-time dimensionality reduction of streaming signals.

Algorithm: Uses a modified Oja's rule with anti-Hebbian lateral connections:

y = Wᵀ · (x − μ)                     (project)
W ← W + η · (x − μ) · yᵀ − η · W · yyᵀ  (update)

The second term enforces decorrelation between components. Periodic QR orthonormalisation prevents numerical drift.

Learning Rate: Decays as η = η₀ / √n where n is the sample count.

Variance Tracking: Per-component and total variance are estimated via exponential moving averages (EMA), enabling real-time explained-variance-ratio monitoring.

Input: MathNet.Numerics.LinearAlgebra.Vector<T> or MathNet.Numerics.LinearAlgebra.Matrix<T> of double (matrix rows processed sequentially).

Output: MathNet.Numerics.LinearAlgebra.Vector<T> of double — the k-dimensional projection.

Constructors

OnlinePCA(string, double, int, double, int, int)

Initializes a new OnlinePCA instance.

Declaration
public OnlinePCA(string name, double desiredRate = 0, int k = 2, double eta0 = 0.2, int reorthEvery = 100, int minStableCount = 500)
Parameters
Type Name Description
string name

Display name of the block.

double desiredRate

Desired processing rate in Hz. 0 = inherited from upstream.

int k

Number of principal components (must be 2 or 3 for visualisation).

double eta0

Initial learning rate η₀. Decays as η₀/√n.

int reorthEvery

QR orthonormalisation frequency in samples.

int minStableCount

Minimum samples before the model is considered stable.

Exceptions
Type Condition
ArgumentOutOfRangeException

Thrown when k is not 2 or 3.

Fields

_W

Loadings matrix W (d × k). Columns are the principal component directions.

Declaration
private Matrix<double> _W
Field Value
Type Description
Matrix<double>

_d

Input dimensionality (set on first sample).

Declaration
private int _d
Field Value
Type Description
int

_emaAlpha

EMA smoothing factor α (0 < α < 1).

Declaration
private readonly double _emaAlpha
Field Value
Type Description
double

_eta0

Initial learning rate η₀. Actual rate decays as η₀/√n.

Declaration
private readonly double _eta0
Field Value
Type Description
double

_isStable

Whether model has reached stable state.

Declaration
private bool _isStable
Field Value
Type Description
bool

_k

Number of principal components to extract.

Declaration
private readonly int _k
Field Value
Type Description
int

_mean

Running mean estimate μ (d-dimensional), updated via Welford's algorithm.

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

_pcVarEma

EMA of per-component variance (y² per component).

Declaration
private Vector<double> _pcVarEma
Field Value
Type Description
Vector<double>

_prevPC1

Previous PC1 direction for sign correction.

Declaration
private Vector<double>? _prevPC1
Field Value
Type Description
Vector<double>

_prevPC2

Previous PC2 direction for sign correction.

Declaration
private Vector<double>? _prevPC2
Field Value
Type Description
Vector<double>

_prevPC3

Previous PC3 direction for sign correction.

Declaration
private Vector<double>? _prevPC3
Field Value
Type Description
Vector<double>

_reorthEvery

Frequency of QR orthonormalisation (every N samples).

Declaration
private readonly int _reorthEvery
Field Value
Type Description
int

_totalVarEma

EMA of total input variance (‖x − μ‖²).

Declaration
private double _totalVarEma
Field Value
Type Description
double

_xc

Preallocated centred input vector.

Declaration
private Vector<double>? _xc
Field Value
Type Description
Vector<double>

_y

Preallocated projected output vector.

Declaration
private Vector<double>? _y
Field Value
Type Description
Vector<double>

_yyT

Preallocated outer product matrix y·yᵀ (k × k).

Declaration
private Matrix<double>? _yyT
Field Value
Type Description
Matrix<double>

Properties

ComponentCount

Gets the number of principal components (k).

Declaration
public int ComponentCount { get; }
Property Value
Type Description
int

DumpFilePrefix

Recordings from this block are named <block>_projection.csv.

Declaration
protected override string DumpFilePrefix { get; }
Property Value
Type Description
string
Overrides
BaseBlock.DumpFilePrefix

ExplainedVariance

Gets the EMA-estimated variance captured by each principal component.

Declaration
public Vector<double> ExplainedVariance { get; }
Property Value
Type Description
Vector<double>

ExplainedVarianceRatio

Gets the ratio of variance explained by each component relative to total variance.

Declaration
public Vector<double> ExplainedVarianceRatio { get; }
Property Value
Type Description
Vector<double>
Remarks

Each element is Var(PCᵢ) / TotalVar. Returns zeros if total variance is negligible.

IsStable

Gets whether the model has reached a stable state.

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

Loadings

Gets the loadings matrix W (d × k). Columns are the principal component directions.

Declaration
public Matrix<double> Loadings { get; }
Property Value
Type Description
Matrix<double>

Mean

Gets the current mean estimate μ.

Declaration
public Vector<double> Mean { get; }
Property Value
Type Description
Vector<double>

SampleCount

Gets the total number of samples processed.

Declaration
public long SampleCount { get; }
Property Value
Type Description
long

TotalVariance

Gets the EMA-estimated total input variance.

Declaration
public double TotalVariance { get; }
Property Value
Type Description
double

Methods

ConfigureInput(IServiceProvider, JsonModel)

Creates and configures an OnlinePCA instance from a JSON model definition.

Declaration
public static OnlinePCA ConfigureInput(IServiceProvider sp, JsonModel m)
Parameters
Type Name Description
IServiceProvider sp

Service provider for dependency injection.

JsonModel m

The JSON model. See class-level <example> for expected Params layout.

Returns
Type Description
OnlinePCA

A fully configured OnlinePCA instance.

CorrectPCSigns()

Corrects the sign of principal component directions for temporal consistency.

Declaration
private void CorrectPCSigns()
Remarks

PCA eigenvectors have inherent sign ambiguity. 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.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration
public override void Dispose()
Overrides
BaseBlock.Dispose()

EnsureInit(int)

Ensures all internal state is properly initialised for the given input dimension.

Declaration
private void EnsureInit(int d)
Parameters
Type Name Description
int d

Input vector dimensionality.

Exceptions
Type Condition
ArgumentOutOfRangeException

Thrown when d ≤ 0.

GetJsonParams()

Exports the block's parameters in the exact order ConfigureInput(IServiceProvider, JsonModel) reads them, so a saved graph reloads with the same configuration. SupervisedPCA inherits this override because its own ConfigureInput reads the same four values in the same order.

Declaration
protected override IReadOnlyList<object>? GetJsonParams()
Returns
Type Description
IReadOnlyList<object>

k, η₀, reorthonormalisation interval and minimum stable count.

Overrides
BaseBlock.GetJsonParams()

OnReceive(object, object)

Handles incoming data from the pipeline.

Declaration
protected override void OnReceive(object sender, object data)
Parameters
Type Name Description
object sender

The upstream block.

object data

MathNet.Numerics.LinearAlgebra.Vector<T> (single observation) or MathNet.Numerics.LinearAlgebra.Matrix<T> (rows processed sequentially).

Overrides
BaseBlock.OnReceive(object, object)

Orthonormalize(ref Matrix<double>)

Orthonormalises the columns of W using QR decomposition.

Declaration
private static void Orthonormalize(ref Matrix<double> W)
Parameters
Type Name Description
Matrix<double> W

Matrix to orthonormalise (modified in place).

OuterProductTo(Matrix<double>, Vector<double>)

Computes the outer product y·yᵀ and writes the result into dst.

Declaration
private static void OuterProductTo(Matrix<double> dst, Vector<double> v)
Parameters
Type Name Description
Matrix<double> dst

Destination matrix (k × k). Overwritten in place.

Vector<double> v

Source vector (k-dimensional).

Process(Vector<double>)

Processes a single input vector through the online PCA pipeline.

Declaration
protected virtual void Process(Vector<double> x)
Parameters
Type Name Description
Vector<double> x

Input observation vector (d-dimensional).

Remarks

Processing steps:

  1. Update running mean (Welford's algorithm).
  2. Centre the input: xc = x − μ.
  3. Project: y = Wᵀ · xc.
  4. Update EMA variance estimates.
  5. Oja update: W ← W + η·xc·yᵀ − η·W·yyᵀ.
  6. Periodic: QR orthonormalise W and correct PC signs.
  7. Publish the k-dimensional projection.
Exceptions
Type Condition
ArgumentNullException

Thrown when x is null.

Project(Vector<double>)

Projects a single observation into the PCA subspace using the current loadings.

Declaration
public Vector<double> Project(Vector<double> x)
Parameters
Type Name Description
Vector<double> x

Input observation vector (d-dimensional).

Returns
Type Description
Vector<double>

The k-dimensional PCA projection.

Remarks

Does not update any internal state. Use for inference after training.

Exceptions
Type Condition
InvalidOperationException

Thrown when PCA has not been initialised.

ArgumentNullException

Thrown when x is null.

InvalidOperationException

Thrown when dimension does not match.

PublishProjection(Vector<double>)

Publishes the principal component projection to downstream subscribers.

Declaration
protected virtual void PublishProjection(Vector<double> projection)
Parameters
Type Name Description
Vector<double> projection

The k-dimensional projection vector.

Remarks

Protected virtual to allow interception or modification in derived classes (e.g., SupervisedPCA).

Reconstruct(Vector<double>)

Reconstructs an approximation of the original signal from principal component projections.

Declaration
public Vector<double> Reconstruct(Vector<double> y)
Parameters
Type Name Description
Vector<double> y

Principal component vector (k-dimensional).

Returns
Type Description
Vector<double>

Reconstructed observation vector (d-dimensional).

Remarks

Applies x̂ = W · y + μ. If k < d, information is lost and perfect reconstruction is not possible.

Exceptions
Type Condition
InvalidOperationException

Thrown when PCA has not been initialised.

ArgumentNullException

Thrown when y is null.

InvalidOperationException

Thrown when dimension does not match k.

Reset()

Resets all learned parameters to initial state.

Declaration
public void Reset()
Remarks

Clears mean, loadings, variance estimates, and sign-correction history. The next Process(Vector<double>) call will trigger full re-initialisation.

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.

Implements

INotifyPropertyChanged
INotifyPropertyChanging
ISubscriber
IPublisher
IBaseBlockProps
IJsonExportable
IDisposable
IAsyncDisposable

Search documentation

Start typing to search the documentation.