Factorization APIs#

Principal component analysis and the SVD#

class aoclda.factorization.PCA(n_components=1, bias='unbiased', method='covariance', solver='auto', store_U=False, precision='double')#

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.

  • precision (str, optional) – Whether to initialize the PCA object in double or single precision. It can take the values ‘single’ or ‘double’. Default = ‘double’.

property column_means#

The column means of the data matrix. These are computed if method = 'correlation' 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 (numpy.ndarray) – 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 (numpy.ndarray) – 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 (numpy.ndarray) – 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, in column major format.

  • lda – [in] the leading dimension of the data matrix. Constraint: lda \(\ge\) n_samples.

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 column major format in decreasing order of explained variance.

  • da_pca_scores - return an array of size n_samples \(\times\) n_components containing the scores in column major format.

  • 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 column major format.

  • 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 column major format.

  • 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 column major format.

  • ldx – [in] the leading dimension of the data matrix. Constraint: ldx \(\ge\) m_samples.

  • X_transform – [out] an array of size at least m_samples \(\times\) n_components, in which the transformed data will be stored (in column major format).

  • ldx_transform – [in] the leading dimension of X_transform. Constraint: ldx_transform \(\ge\) m_samples.

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 column major format.

  • ldy – [in] the leading dimension of the data matrix. Constraint: ldy \(\ge\) k_samples.

  • Y_inv_transform – [out] an array of size at least k_samples \(\times\) n_features, in which the transformed data will be stored (in column major format).

  • ldy_inv_transform – [in] the leading dimension of Y_inv_transform. Constraint: ldy_inv_transform \(\ge\) k_samples.

Returns

da_status. The function returns: