fsml_pca Interface

public interface fsml_pca

Principal Component Analysis (PCA) or Empirical Orthogonal Function (EOF) analysis is a procedure that reduces the dimensionality of multivariate data by identifying a set of orthogonal vectors (eigenvectors or EOFs) that represent directions of maximum variance in the dataset. EOF analysis is often used interchangably with the geographically weighted PCA. As they are mathematically identical, a single pca procedure is offered with optional arguments and outputs that also makes it usable as a classic EOF analysis.

For a classic PCA, the input matrix x is assumed to contain observations in rows and variables in columns.

For a classic EOF analysis, the input matrix x is assumed to contain time in rows and space in columns.

Optionally, the data can be standardised (using the correlation matrix) and/or column-wise weights can be applied prior to analysis. While the latter is unusual for a standard PCA, it is common for EOF analysis (geographically weighted PCA as often applied in geographical sciences).

The covariance or correlation matrix $\mathbf{C}$ is computed as: $$\mathbf{C} = \frac{1}{m - 1} \mathbf{X}^\top \mathbf{X}$$ where: - $\mathbf{X}$ is the preprocessed (centred and optionally standardised) data matrix, - $m$ is the number of observations (rows in x).

A symmetric eigen-decomposition is performed: $$\mathbf{C} \mathbf{E} = \mathbf{E} \Lambda$$ where: - $\mathbf{E}$ contains the eigenvectors (EOFs), - $\Lambda$ is a diagonal matrix of eigenvalues representing variance explained.

The principal components (PCs) are given by: $$\mathbf{PC} = \mathbf{X} \mathbf{E}$$

The explained variance for each component is computed as: $$r^2_j = \frac{\lambda_j}{\sum_k \lambda_k} \times 100$$

EOFs may optionally be scaled for plotting: $$\text{EOF}_{\text{scaled}} = \text{EOF} \cdot \sqrt{\lambda_j}$$

This subroutine uses eigh from the stdlib_linalg module to compute eigenvalues and eigenvectors of the symmetric covariance matrix.

Input arguments:

• x(m,n): Input data matrix (observations × variables)
• m: Number of rows (observations)
• n: Number of columns (variables)
• opt: (Optional) Use 0 for covariance matrix, 1 for correlation matrix (default: 1)
• wt(n): (Optional) Column weights (default: equal weights)

Output arguments:

• pc(m,n): Principal components (scores)
• eof(n,n): EOFs / eigenvectors (unweighted)
• ev(n): Eigenvalues (explained variance)
• r2(n): (Optional) Percentage of variance explained by each component
• eof_scaled(n,n): (Optional) EOFs scaled by square root of eigenvalues

The number of valid EOF/PC modes is determined by the number of non-zero eigenvalues. Arrays are initialised to zero and populated only where eigenvalues are strictly positive.

Module Procedures