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:
| Index | Description |
|---|---|
| 0 | k (int) — Number of principal components (2 or 3). Default: 2. |
| 1 | eta0 (double) — Initial learning rate η₀. Default: 0.2. |
| 2 | reorthEvery (int) — QR orthonormalisation frequency in samples. Default: 100. |
| 3 | minStableCount (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
Implements
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 |
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
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 |
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
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 |
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
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
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:
- Update running mean (Welford's algorithm).
- Centre the input: xc = x − μ.
- Project: y = Wᵀ · xc.
- Update EMA variance estimates.
- Oja update: W ← W + η·xc·yᵀ − η·W·yyᵀ.
- Periodic: QR orthonormalise W and correct PC signs.
- Publish the k-dimensional projection.
Exceptions
| Type | Condition |
|---|---|
| ArgumentNullException | Thrown when |
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 |
| 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 |
| 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. |