Principal component analysis and the SVD - Principal component analysis and the SVD - 5.3 English - 68552

AOCL API Guide (68552)
Document_ID
68552
Release_Date
2026-05-13
Version
5.3 English
class aoclda.factorization.PCA(n_components=1, bias='unbiased', method='covariance', solver='auto', store_U=False, whiten=False, check_data=False)#

Principal component analysis (PCA).

Find all or some of the principal components of a data matrix.

Parameters:

  • n_components (int, optional) – Number of components to keep. Default=1.

  • bias (str, optional) – Whether to use unbiased or biased estimators for standard deviations and variances. It can take the values ‘unbiased’ or ‘biased’. Default: ‘unbiased’.

  • method (str, optional) –

    The method used to compute the PCA. Default = ‘covariance’.

    • If method = 'covariance' then the columns are mean-centered so the PCA is based on the covariance matrix.

    • If method = 'correlation' then the columns are mean-centered and scaled by the standard deviation so the PCA is based on the correlation matrix.

    • If method = 'svd' then no normalization occurs so the PCA reduces to the singular value decomposition.

  • solver (str, optional) – Which LAPACK solver to use to compute the underlying singular value decomposition, allowed values: ‘auto’, ‘gesdd’, ‘gesvd’, ‘gesvdx’, ‘syevd’. If solver = 'syevd' then then the SVD will be found by explicitly forming the covariance or correlation matrix and performing an eigendecomposition. This is very fast for tall, thin data matrices but for wider matrices it requires a lot of memory. The method is also more susceptible to ill-conditioning so must be used with care. It is incompatible with the ‘store_U’ option. If solver = 'auto' then ‘gesdd’ will be used unless internal heuristics determine that eigendecomposition using syevd is quicker. Default=’auto’.

  • store_U (bool, optional) – Controls whether to store the matrix U from the singular value decomposition. This allows deterministic results regarding the sign of the principal components, at the expense of some extra computation. This option cannot be used if solver = 'syevd'. Default = False.

  • check_data (bool, optional) – Whether to check the data for NaNs. Default = False.

  • whiten (bool, optional) – Whether to whiten the data upon transformation. This divides each principal component by its corresponding singular value and multiplies the component by a dimensional factor so the transformed data, specifically that data used to fit the PCA, has a unit diagonal covariance matrix. Default = False.

property column_means#

The column means of the data matrix. These are computed if method = 'covariance' or method = 'correlation'.

Type:

numpy.ndarray of shape (n_features, )

property column_sdevs#

The column standard deviations of the data matrix. These are only computed if method = 'correlation'

Type:

numpy.ndarray of shape (n_features, )

fit(A)#

Computes the principal component analysis on the supplied data matrix.

Parameters:

A (array-like) – The data matrix with which to compute the PCA. It has shape (n_samples, n_features).

Returns:

Returns the instance itself.

Return type:

self (object)

inverse_transform(Y)#

Transform a data matrix into the original coordinate space.

Transforms a data matrix Y in the new feature space back into the original coordinate space used by the matrix which was supplied to pca.fit. The transformation is computed by projecting Y into the original coordinate space, then inverting any standardization used on the original data matrix.

Parameters:

Y (array-like) – The data matrix to be transformed. It has shape (k_samples, k_features). Note that k_features must match n_components, the number of principal components computed by pca.fit.

Returns:

The transformed matrix.

Return type:

numpy.ndarray of shape (k_samples, n_features)

property n_components#

The number of components found in the PCA.

Type:

int

property n_features#

The number of features in the data matrix used to compute the PCA.

Type:

int

property n_samples#

The number of samples in the data matrix used to compute the PCA.

Type:

int

property principal_components#

Principal axes in feature space, representing the directions of maximum variance in the data. Equivalently, the right singular vectors of the normalized input data, parallel to its eigenvectors. The components are sorted by decreasing variance.

Type:

numpy.ndarray of shape (n_components, n_features)

property scores#

The principal component scores, \(U\Sigma\).

Type:

numpy.ndarray of shape (n_samples, n_components)

property sigma#

The diagonal values of \(\Sigma\) from the SVD.

Type:

numpy.ndarray of shape (n_components,)

property total_variance#

The total amount of variance within the dataset.

Type:

numpy.ndarray of shape (1, )

transform(X)#

Transform a data matrix into new feature space.

Transforms a data matrix X from the original coordinate system into the new coordinates previously computed by pca.fit. The transformation is computed by applying any standardization used on the original data matrix to X, then projecting X into the previously computed principal components.

Parameters:

X (array-like) – The data matrix to be transformed. It has shape (m_samples, m_features). Note that m_features must match n_features, the number of features in the data matrix originally supplied to pca.fit.

Returns:

The transformed matrix.

Return type:

numpy.ndarray of shape (m_samples, n_components)

property u#

The matrix \(U\) from the SVD.

Type:

numpy.ndarray of shape (n_samples, n_samples)

property variance#

The amount of variance explained by each of the selected components.

Type:

numpy.ndarray of shape (n_components, )

property vt#

The matrix \(V^T\) from the SVD.

Type:

numpy.ndarray of shape (n_components, n_features)

da_status da_pca_set_data_s(da_handle handle, da_int n_samples, da_int n_features, const float *A, da_int lda)#
da_status da_pca_set_data_d(da_handle handle, da_int n_samples, da_int n_features, const double *A, da_int lda)#

Pass a data matrix to the da_handle object in preparation for computing the PCA.

A copy of the data matrix is stored internally, to avoid overwriting the user’s data during the computation.

After calling this function you may use the option setting APIs to set options.

Parameters:

  • handle – [inout] a da_handle object, initialized using da_handle_init_? with type da_handle_pca.

  • n_samples – [in] the number of rows of the data matrix, A. Constraint: n_samples \(\ge\) 1.

  • n_features – [in] the number of columns of the data matrix, A. Constraint: n_features \(\ge\) 1.

  • A – [in] the n_samples \(\times\) n_features data matrix. By default, it should be stored in column-major order, unless you have set the storage order option to row-major.

  • lda – [in] the leading dimension of the data matrix. Constraint: lda \(\ge\) n_samples if A is stored in column-major order, or lda \(\ge\) n_features if A is stored in row-major order.

Returns:

da_status. The function returns:

da_status da_pca_compute_s(da_handle handle)#
da_status da_pca_compute_d(da_handle handle)#

Compute PCA.

Computes a principal component analysis on the data matrix previously passed into the handle using da_pca_set_data_?.

Parameters:

handle – [inout] a da_handle object, initialized using da_handle_init_? with type da_handle_pca and with data passed in via da_pca_set_data_?.

Returns:

da_status. The function returns:

Post:

After successful execution, da_handle_get_result_? can be queried with the following enums:

  • da_rinfo - return an array of size 3 containing n_samples, n_features and n_components, the number of principal components found.

  • da_pca_principal_components - return an array of size n_components \(\times\) n_features containing the principal components, in the same storage order as the input data, in decreasing order of explained variance.

  • da_pca_scores - return an array of size n_samples \(\times\) n_components containing the scores in the same storage order as the input data.

  • da_pca_variance - return an array of size n_components containing the amount of variance explained by each principal component.

  • da_pca_total_variance - return an array of size 1 containing the total of variance within the dataset.

  • da_pca_u - return an array of size n_samples \(\times\) n_components containing the matrix \( U \) from the SVD of the standardized data matrix in the same storage order as the input data.

  • da_pca_sigma - return an array of size n_components containing the singular values of the standardized data matrix.

  • da_pca_vt - return an array of size n_components \(\times\) n_features containing the matrix \( V^T \) from the SVD of the standardized data matrix in the same storage order as the input data.

  • da_pca_column_means - return an array of size n_features containing the column means of the data matrix (note this is only available if the option PCA method was set to covariance or correlation).

  • da_pca_column_sdevs - return an array of size n_features containing the column standard deviations (with n_samples \(\ - 1 \) degrees of freedom) of the data matrix (note this is only available if the option PCA method was set to correlation).

da_status da_pca_transform_s(da_handle handle, da_int m_samples, da_int m_features, const float *X, da_int ldx, float *X_transform, da_int ldx_transform)#
da_status da_pca_transform_d(da_handle handle, da_int m_samples, da_int m_features, const double *X, da_int ldx, double *X_transform, da_int ldx_transform)#

Transform a data matrix into new feature space.

Transforms a data matrix X from the original coordinate system into the new coordinates previously computed in da_pca_compute_?. The transformation is computed by applying any standardization used on the original data matrix to X, then projecting X into the previously computed principal components.

Parameters:

  • handle – [inout] a da_handle object, with a PCA previously computed via da_pca_compute_?.

  • m_samples – [in] the number of rows of the data matrix, X. Constraint: m_samples \(\ge\) 1.

  • m_features – [in] the number of columns of the data matrix, X. Constraint: m_features \(=\) n_features, the number of features in the data matrix originally supplied to da_pca_set_data_?.

  • X – [in] the m_samples \(\times\) m_features data matrix, in the same storage format used to fit the model.

  • ldx – [in] the leading dimension of the data matrix. Constraint: ldx \(\ge\) m_samples if X is stored in column-major order, or ldx \(\ge\) m_features if X is stored in row-major order.

  • X_transform – [out] an array of size at least m_samples \(\times\) n_components, in which the transformed data will be stored (in the same storage format used to fit the model).

  • ldx_transform – [in] the leading dimension of X_transform. Constraint: ldx_transform \(\ge\) m_samples if X is stored in column-major order, or ldx_transform \(\ge\) n_components if X is stored in row-major order.

Returns:

da_status. The function returns:

da_status da_pca_inverse_transform_s(da_handle handle, da_int k_samples, da_int k_features, const float *Y, da_int ldy, float *Y_inv_transform, da_int ldy_inv_transform)#
da_status da_pca_inverse_transform_d(da_handle handle, da_int k_samples, da_int k_features, const double *Y, da_int ldy, double *Y_inv_transform, da_int ldy_inv_transform)#

Transform a data matrix into the original coordinate space.

Transforms a data matrix Y in the new feature space back into the original coordinate space used by the matrix which was supplied to da_pca_set_data_?. The transformation is computed by projecting Y into the original coordinate space, then inverting any standardization used on the original data matrix.

Parameters:

  • handle – [inout] a da_handle object, with a PCA previously computed via da_pca_compute_?.

  • k_samples – [in] the number of rows of the data matrix, Y. Constraint: k_samples \(\ge\) 1.

  • k_features – [in] the number of columns of the data matrix, Y. Constraint: k_features \(=\) n_components, the number of PCA components computed by da_pca_compute_?.

  • Y – [in] the k_samples \(\times\) k_features data matrix, in the same storage format used to fit the model.

  • ldy – [in] the leading dimension of the data matrix. Constraint: ldy \(\ge\) k_samples if Y is stored in column-major order, or ldy \(\ge\) k_features if Y is stored in row-major order.

  • Y_inv_transform – [out] an array of size at least k_samples \(\times\) n_features, in which the transformed data will be stored (in the same storage format used to fit the model).

  • ldy_inv_transform – [in] the leading dimension of Y_inv_transform. Constraint: ldy_inv_transform \(\ge\) k_samples if Y is stored in column-major order, or ldy_inv_transform \(\ge\) n_features if Y is stored in row-major order.

Returns:

da_status. The function returns: