update specs

Author: JAi-SATHVIK

doc/specs/stdlib_stats.md

@@ -283,6 +283,110 @@ If `mask` is specified, the result is the _k_-th  (central) moment of all elemen
 {!example/stats/example_moment.f90!}
 ```
 
+## `pca` - Principal Component Analysis
+
+### Status
+
+Experimental
+
+### Description
+
+Performs Principal Component Analysis (PCA) on a 2D array of observations and features.
+The input matrix `x` has shape `(m, n)`, where `m` is the number of observations and `n` is the number of features.
+The subroutine computes the principal components (loadings), the singular values, and optionally the feature means.
+
+Two methods are supported:
+- `"svd"`: (Default) Computes PCA via Singular Value Decomposition of the centered data. This is generally more numerically stable.
+- `"eig"` or `"cov"`: Computes PCA via Eigendecomposition of the covariance matrix.
+
+### Syntax
+
+`call ` [[stdlib_stats(module):pca(interface)]] `(x, components, singular_values [, x_mean [, method [, overwrite_x [, err]]]])`
+
+### Class
+
+Generic subroutine
+
+### Arguments
+
+`x`: Shall be a rank-2 real array with shape `(m, n)`. It is an `intent(inout)` argument. If `overwrite_x` is `.true.`, `x` may be modified during computation.
+
+`components`: Shall be a rank-2 real array with shape `(n_components, n)`. It stores the principal components as rows. It is an `intent(out)` argument.
+
+`singular_values`: Shall be a rank-1 real array with shape `(n_components)`. It stores the singular values in descending order. It is an `intent(out)` argument.
+
+`x_mean` (optional): Shall be a rank-1 real array with shape `(n)`. It stores the mean of each feature (column). It is an `intent(out)` argument.
+
+`method` (optional): Shall be a character string. Either `"svd"` or `"eig"`/`"cov"`. It is an `intent(in)` argument.
+
+`overwrite_x` (optional): Shall be a scalar of type `logical`. If `.true.`, the input matrix `x` can be used as a workspace and modified. It is an `intent(in)` argument.
+
+`err` (optional): Shall be of type `linalg_state_type`. It is an `intent(out)` argument.
+
+### Example
+
+```fortran
+{!example/stats/example_pca.f90!}
+```
+
+## `pca_transform` - Projects data into principal component space
+
+### Status
+
+Experimental
+
+### Description
+
+Projects the input data `x` into the reduced dimensional space defined by the provided principal components.
+The transformation is defined as `x_transformed = (x - x_mean) * components^T`.
+
+### Syntax
+
+`call ` [[stdlib_stats(module):pca_transform(interface)]] `(x, components [, x_mean], x_transformed)`
+
+### Class
+
+Generic subroutine
+
+### Arguments
+
+`x`: Shall be a rank-2 real array with shape `(m, n)`. It is an `intent(in)` argument.
+
+`components`: Shall be a rank-2 real array with shape `(nc, n)`. It stores the principal components as rows. It is an `intent(in)` argument.
+
+`x_mean` (optional): Shall be a rank-1 real array with shape `(n)`. It stores the feature means to subtract. It is an `intent(in)` argument.
+
+`x_transformed`: Shall be a rank-2 real array with shape `(m, nc)`. It stores the projected data. It is an `intent(out)` argument.
+
+## `pca_inverse_transform` - Reconstructs original data from principal component space
+
+### Status
+
+Experimental
+
+### Description
+
+Reconstructs the original data representation from the principal component space.
+The reconstruction is defined as `x_reconstructed = x_reduced * components + x_mean`.
+
+### Syntax
+
+`call ` [[stdlib_stats(module):pca_inverse_transform(interface)]] `(x_reduced, components [, x_mean], x_reconstructed)`
+
+### Class
+
+Generic subroutine
+
+### Arguments
+
+`x_reduced`: Shall be a rank-2 real array with shape `(m, nc)`. It is an `intent(in)` argument.
+
+`components`: Shall be a rank-2 real array with shape `(nc, n)`. It stores the principal components as rows. It is an `intent(in)` argument.
+
+`x_mean` (optional): Shall be a rank-1 real array with shape `(n)`. It stores the feature means to add back. It is an `intent(in)` argument.
+
+`x_reconstructed`: Shall be a rank-2 real array with shape `(m, n)`. It stores the reconstructed data. It is an `intent(out)` argument.
+
 ## `var` - variance of array elements
 
 ### Status

example/stats/example_pca.f90

@@ -0,0 +1,50 @@
+program example_pca
+    use stdlib_kinds, only: dp
+    use stdlib_stats, only: pca, pca_transform, pca_inverse_transform
+    use stdlib_linalg_state, only: linalg_state_type
+    implicit none
+
+    real(dp) :: x(3, 2), components(2, 2), s(2), mu(2)
+    real(dp) :: x_trans(3, 2), x_inv(3, 2)
+    type(linalg_state_type) :: err
+    integer :: i
+
+    ! Input data: 3 observations, 2 features
+    x = reshape([1.0_dp, 3.0_dp, 5.0_dp, 2.0_dp, 4.0_dp, 6.0_dp], [3, 2])
+
+    print *, "Original data:"
+    do i = 1, 3
+        print "(2f6.2)", x(i, :)
+    end do
+
+    ! Perform PCA
+    call pca(x, components, s, x_mean=mu, err=err)
+
+    if (err%ok()) then
+        print *, ""
+        print *, "Feature means:", mu
+        print *, "Singular values:", s
+        print *, "Principal components (as rows):"
+        print "(2f6.3)", components(1, :)
+        print "(2f6.3)", components(2, :)
+
+        ! Transform data to principal components space
+        call pca_transform(x, components, mu, x_trans)
+        print *, ""
+        print *, "Transformed data (projected):"
+        do i = 1, 3
+            print "(2f8.3)", x_trans(i, :)
+        end do
+
+        ! Inverse transform to reconstruct original data
+        call pca_inverse_transform(x_trans, components, mu, x_inv)
+        print *, ""
+        print *, "Reconstructed data:"
+        do i = 1, 3
+            print "(2f6.2)", x_inv(i, :)
+        end do
+    else
+        print *, "PCA failed: ", err%message
+    end if
+
+end program example_pca