:mod:`heat.decomposition.pca` ============================= .. py:module:: heat.decomposition.pca .. autoapi-nested-parse:: Module implementing decomposition techniques, such as PCA. Module Contents --------------- .. py:class:: PCA(n_components: Optional[Union[int, float]] = None, copy: bool = True, whiten: bool = False, svd_solver: str = 'hierarchical', tol: Optional[float] = None, iterated_power: Union[str, int] = 0, n_oversamples: int = 10, power_iteration_normalizer: str = 'qr', random_state: Optional[int] = None) Bases: :class:`heat.TransformMixin`, :class:`heat.BaseEstimator` Pricipal Component Analysis (PCA). Linear dimensionality reduction using Singular Value Decomposition of the data to project it to a lower dimensional space. The input data is centered but not scaled for each feature before applying the SVD. :param n_components: Number of components to keep. If n_components is not set all components are kept. If n_components is an integer, it specifies the number of components to keep. If n_components is a float between 0 and 1, it specifies the fraction of variance explained by the components to keep. :type n_components: int, float, None, default=None :param copy: In-place operations are not yet supported. Please set copy=True. :type copy: bool, default=True :param whiten: Not yet supported. :type whiten: bool, default=False :param svd_solver: 'full' : Full SVD is performed. In general, this is more accurate, but also slower. So far, this is only supported for tall-skinny or short-fat data. 'hierarchical' : Hierarchical SVD, i.e., an algorithm for computing an approximate, truncated SVD, is performed. Only available for data split along axis no. 0. 'randomized' : Randomized SVD is performed. :type svd_solver: {'full', 'hierarchical'}, default='hierarchical' :param tol: Not yet necessary as iterative methods for PCA are not yet implemented. :type tol: float, default=None :param iterated_power: if svd_solver='randomized', this parameter is the number of iterations for the power method. Choosing `iterated_power > 0` can lead to better results in the case of slowly decaying singular values but is computationally more expensive. :type iterated_power: int, default=0 :param n_oversamples: if svd_solver='randomized', this parameter is the number of additional random vectors to sample the range of X so that the range of X can be approximated more accurately. :type n_oversamples: int, default=10 :param power_iteration_normalizer: if svd_solver='randomized', this parameter is the normalization form of the iterated power method. So far, only QR is supported. :type power_iteration_normalizer: {'qr'}, default='qr' :param random_state: if svd_solver='randomized', this parameter allows to set the seed for the random number generator. :type random_state: int, default=None :ivar components_: Principal axes in feature space, representing the directions of maximum variance in the data. The components are sorted by explained_variance_. :vartype components_: DNDarray of shape (n_components, n_features) :ivar explained_variance_: The amount of variance explained by each of the selected components. Not supported by svd_solver='hierarchical' and svd_solver='randomized'. :vartype explained_variance_: DNDarray of shape (n_components,) :ivar explained_variance_ratio_: Percentage of variance explained by each of the selected components. Not supported by svd_solver='hierarchical' and svd_solver='randomized'. :vartype explained_variance_ratio_: DNDarray of shape (n_components,) :ivar total_explained_variance_ratio_: The percentage of total variance explained by the selected components together. For svd_solver='hierarchical', an lower estimate for this quantity is provided; see :func:`ht.linalg.hsvd_rtol` and :func:`ht.linalg.hsvd_rank` for details. Not supported by svd_solver='randomized'. :vartype total_explained_variance_ratio_: float :ivar singular_values_: The singular values corresponding to each of the selected components. Not supported by svd_solver='hierarchical' and svd_solver='randomized'. :vartype singular_values_: DNDarray of shape (n_components,) :ivar mean_: Per-feature empirical mean, estimated from the training set. :vartype mean_: DNDarray of shape (n_features,) :ivar n_components_: The estimated number of components. :vartype n_components_: int :ivar n_samples_: Number of samples in the training data. :vartype n_samples_: int :ivar noise_variance_: not yet implemented :vartype noise_variance_: float .. rubric:: Notes Hierarchical SVD (`svd_solver = "hierarchical"`) computes an approximate, truncated SVD. Thus, the results are not exact, in general, unless `n_components` chosen is larger than the actual rank (=matrix rank) of the underlying data; see :func:`ht.linalg.hsvd_rank` and :func:`ht.linalg.hsvd_rtol` for details. Randomized SVD (`svd_solver = "randomized"`) is a stochastic algorithm that computes an approximate, truncated SVD. .. attribute:: n_components :annotation: = None .. attribute:: copy :annotation: = True .. attribute:: whiten :annotation: = False .. attribute:: svd_solver :annotation: = 'hierarchical' .. attribute:: tol :annotation: = None .. attribute:: iterated_power :annotation: = 0 .. attribute:: n_oversamples :annotation: = 10 .. attribute:: power_iteration_normalizer :annotation: = 'qr' .. attribute:: random_state :annotation: = None .. attribute:: components_ :annotation: = None .. attribute:: explained_variance_ :annotation: = None .. attribute:: explained_variance_ratio_ :annotation: = None .. attribute:: total_explained_variance_ratio_ :annotation: = None .. attribute:: singular_values_ :annotation: = None .. attribute:: mean_ :annotation: = None .. attribute:: n_components_ :annotation: = None .. attribute:: n_samples_ :annotation: = None .. attribute:: noise_variance_ :annotation: = None .. role:: raw-html(raw) :format: html .. method:: fit(X: heat.DNDarray, y=None) -> Self Fit the PCA model with data X. :param X: Data set of which PCA has to be computed. :type X: DNDarray of shape (n_samples, n_features) :param y: Not used, present for API consistency by convention. :type y: Ignored .. method:: transform(X: heat.DNDarray) -> heat.DNDarray Apply dimensionality based on PCA to X. :param X: Data set to be transformed. :type X: DNDarray of shape (n_samples, n_features) .. method:: inverse_transform(X: heat.DNDarray) -> heat.DNDarray Transform data back to its original space. :param X: Data set to be transformed back. :type X: DNDarray of shape (n_samples, n_components) .. py:class:: IncrementalPCA(n_components: Optional[int] = None, copy: bool = True, whiten: bool = False, batch_size: Optional[int] = None) Bases: :class:`heat.TransformMixin`, :class:`heat.BaseEstimator` Incremental Principal Component Analysis (PCA). This class allows for incremental updates of the PCA model. This is especially useful for large data sets that do not fit into memory. An example how to apply this class is given in, e.g., `benchmarks/cb/decomposition.py`. :param n_components: Number of components to keep. If `n_components` is not set all components are kept (default). :type n_components: int, optional :param copy: In-place operations are not yet supported. Please set `copy=True`. :type copy: bool, default=True :param whiten: Not yet supported. :type whiten: bool, default=False :param batch_size: Currently not needed and only added for API consistency and possible future extensions. :type batch_size: int, optional :ivar components_: Principal axes in feature space, representing the directions of maximum variance in the data. The components are sorted by `explained_variance_. :vartype components_: DNDarray of shape (n_components, n_features) :ivar singular_values_: The singular values corresponding to each of the selected components. :vartype singular_values_: DNDarray of shape (n_components,) :ivar mean_: Per-feature empirical mean, estimated from the training set. :vartype mean_: DNDarray of shape (n_features,) :ivar n_components_: The estimated number of components. :vartype n_components_: int :ivar n_samples_seen_: Number of samples processed so far. :vartype n_samples_seen_: int .. attribute:: whiten :annotation: = False .. attribute:: n_components :annotation: = None .. attribute:: batch_size :annotation: = None .. attribute:: components_ :annotation: = None .. attribute:: singular_values_ :annotation: = None .. attribute:: mean_ :annotation: = None .. attribute:: n_components_ :annotation: = None .. attribute:: batch_size_ :annotation: = None .. attribute:: n_samples_seen_ :annotation: = 0 .. role:: raw-html(raw) :format: html .. method:: fit(path: str, chunk_size: int, dataset: str = 'DATA') -> Self Fit the IncrementalPCA model using data loaded in chunks from a HDF5 file. This method processes data incrementally, loading chunks of data from a file and updating the PCA model iteratively. It is particularly useful for large datasets that cannot fit into memory. :param path: Path to the file containing the dataset. The file must be in HDF5 format. :type path: str :param chunk_size: Number of rows to load and process in each chunk. Must be smaller than or equal to the total number of rows in the dataset. :type chunk_size: int :param dataset: Name of the dataset within the file to load. :type dataset: str, default="DATA" :returns: The fitted IncrementalPCA instance. :rtype: Self :raises ValueError: If the file format is not HDF5. If `chunk_size` is larger than the number of rows in the dataset. If the number of columns is smaller than the number of processes. .. method:: partial_fit(X: heat.DNDarray, y=None) One single step of incrementally building up the PCA. Input X is the current batch of data that needs to be added to the existing PCA. .. method:: transform(X: heat.DNDarray) -> heat.DNDarray Apply dimensionality based on PCA to X. :param X: Data set to be transformed. :type X: DNDarray of shape (n_samples, n_features) .. method:: inverse_transform(X: heat.DNDarray) -> heat.DNDarray Transform data back to its original space. :param X: Data set to be transformed back. :type X: DNDarray of shape (n_samples, n_components)