# IncrementalPCA

### *class* cuml.decomposition.IncrementalPCA(, n_components=None, whiten=False, copy=True, batch_size=None, verbose=False, output_type=None)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/decomposition/incremental_pca.py#L23)

Based on sklearn.decomposition.IncrementalPCA from scikit-learn 0.23.1

Incremental principal components analysis (IPCA).
Linear dimensionality reduction using Singular Value Decomposition of
the data, keeping only the most significant singular vectors to
project the data to a lower dimensional space. The input data is
centered but not scaled for each feature before applying the SVD.
Depending on the size of the input data, this algorithm can be much
more memory efficient than a PCA, and allows sparse input.
This algorithm has constant memory complexity, on the order of
`batch_size * n_features`, enabling use of np.memmap files without
loading the entire file into memory. For sparse matrices, the input
is converted to dense in batches (in order to be able to subtract the
mean) which avoids storing the entire dense matrix at any one time.
The computational overhead of each SVD is
`O(batch_size * n_features ** 2)`, but only 2 \* batch_size samples
remain in memory at a time. There will be `n_samples / batch_size`
SVD computations to get the principal components, versus 1 large SVD
of complexity `O(n_samples * n_features ** 2)` for PCA.

* **Parameters:**
  **n_components**
  : Number of components to keep. If `n_components` is `None`,
    then `n_components` is set to `min(n_samples, n_features)`.

  **whiten**
  : If True, de-correlates the components. This is done by dividing them by
    the corresponding singular values then multiplying by sqrt(n_samples).
    Whitening allows each component to have unit variance and removes
    multi-collinearity. It might be beneficial for downstream
    tasks like LinearRegression where correlated features cause problems.

  **copy**
  : If False, X will be overwritten. `copy=False` can be used to
    save memory but is unsafe for general use.

  **batch_size**
  : The number of samples to use for each batch. Only used when calling
    [`fit`](#cuml.decomposition.IncrementalPCA.fit). If `batch_size` is `None`, then `batch_size`
    is inferred from the data and set to `5 * n_features`, to provide a
    balance between approximation accuracy and memory consumption.

  **verbose**
  : Sets logging level. It must be one of `cuml.common.logger.level_*`.
    See [Verbosity Levels](../../cuml/index.html.md#verbosity-levels) for more info.

  **output_type**
  : Return results and set estimator attributes to the indicated output
    type. If None, the output type set at the module level
    (`cuml.global_settings.output_type`) will be used. See
    [Output Data Type Configuration](../../cuml/index.html.md#output-data-type-configuration) for more info.
* **Attributes:**
  **components_**
  : Components with maximum variance.

  **explained_variance_**
  : Variance explained by each of the selected components.

  **explained_variance_ratio_**
  : Percentage of variance explained by each of the selected components.
    If all components are stored, the sum of explained variances is equal
    to 1.0.

  **singular_values_**
  : The singular values corresponding to each of the selected components.
    The singular values are equal to the 2-norms of the `n_components`
    variables in the lower-dimensional space.

  **mean_**
  : Per-feature empirical mean, aggregate over calls to [`partial_fit`](#cuml.decomposition.IncrementalPCA.partial_fit).

  **var_**
  : Per-feature empirical variance, aggregate over calls to
    [`partial_fit`](#cuml.decomposition.IncrementalPCA.partial_fit).

  **noise_variance_**
  : The estimated noise covariance following the Probabilistic PCA model
    from [[4]](#r432b4d28aea3-4).

  **n_components_**
  : The estimated number of components. Relevant when
    `n_components=None`.

  **n_samples_seen_**
  : The number of samples processed by the estimator. Will be reset on
    new calls to fit, but increments across [`partial_fit`](#cuml.decomposition.IncrementalPCA.partial_fit) calls.

  **batch_size_**
  : Inferred batch size from `batch_size`.

### Methods

| [`fit`](#cuml.decomposition.IncrementalPCA.fit)(X[, y])                      | Fit the model with X, using minibatches of size batch_size.   |
|-----------------------------------------------------------------------------------|---------------------------------------------------------------|
| [`partial_fit`](#cuml.decomposition.IncrementalPCA.partial_fit)(X[, y, check_input]) | Incremental fit with X.                                       |
| [`transform`](#cuml.decomposition.IncrementalPCA.transform)(X)                     | Apply dimensionality reduction to X.                          |

### Notes

Implements the incremental PCA model from [[1]](#r432b4d28aea3-1). This model is an extension
of the Sequential Karhunen-Loeve Transform from [[2]](#r432b4d28aea3-2). We have specifically
abstained from an optimization used by authors of both papers, a QR
decomposition used in specific situations to reduce the algorithmic
complexity of the SVD. The source for this technique is [[3]](#r432b4d28aea3-3). This
technique has been omitted because it is advantageous only when decomposing
a matrix with `n_samples >= 5/3 * n_features` where `n_samples` and
`n_features` are the matrix rows and columns, respectively. In addition,
it hurts the readability of the implemented algorithm. This would be a good
opportunity for future optimization, if it is deemed necessary.

### References

### Examples

```python
>>> from cuml.decomposition import IncrementalPCA
>>> import cupy as cp
>>> import cupyx
>>>
>>> X = cupyx.scipy.sparse.random(1000, 4, format='csr',
...                               density=0.07, random_state=5)
>>> ipca = IncrementalPCA(n_components=2, batch_size=200)
>>> ipca.fit(X)
IncrementalPCA(batch_size=200, n_components=2)
>>>
>>> # Components:
>>> ipca.components_
array([[ 0.23698335, -0.06073393,  0.04310868,  0.9686547 ],
       [ 0.27040346, -0.57185116,  0.76248786, -0.13594291]])
>>>
>>> # Singular Values:
>>> ipca.singular_values_
array([5.06637586, 4.59406975])
>>>
>>> # Explained Variance:
>>> ipca.explained_variance_
array([0.02569386, 0.0211266 ])
>>>
>>> # Explained Variance Ratio:
>>> ipca.explained_variance_ratio_
array([0.30424536, 0.25016372])
>>>
>>> # Mean:
>>> ipca.mean_
array([0.02693948, 0.0326928 , 0.03818463, 0.03861492])
>>>
>>> # Noise Variance:
>>> ipca.noise_variance_.item()
0.0037122774558343763
```

<!-- !! processed by numpydoc !! -->

#### as_sklearn()[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/internals/interop.py#L206)

Convert this estimator into an equivalent scikit-learn (or scikit-learn
extension) estimator.

* **Returns:**
  sklearn.base.BaseEstimator
  : A scikit-learn compatible estimator instance that mirrors the trained
    state of the current estimator.

<!-- !! processed by numpydoc !! -->

#### fit(X, y=None) → [IncrementalPCA](#cuml.decomposition.IncrementalPCA)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/decomposition/incremental_pca.py#L201)

Fit the model with X, using minibatches of size batch_size.

* **Parameters:**
  **X**
  : Training data, where n_samples is the number of samples and
    n_features is the number of features.

  **y**
* **Returns:**
  **self**
  : Returns the instance itself.

<!-- !! processed by numpydoc !! -->

#### fit_transform(self, X, y=None)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/decomposition/pca.pyx#L501)

Fit the model with X and apply the dimensionality reduction on X.

* **Parameters:**
  **X**
  : Dense or sparse matrix with dtype float32 or float64.
    Acceptable dense formats: CUDA array interface compliant objects like
    CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas
    DataFrame/Series.

  **y**
  : Dense matrix with dtype float32 or float64.
    Acceptable formats: CUDA array interface compliant objects like
    CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas
    DataFrame/Series.
* **Returns:**
  **trans**
  : Transformed values
    <br/>
    For more information on how to configure cuML’s dense output type,
    refer to: [Output Data Type Configuration](../../cuml/index.html.md#output-data-type-configuration).

<!-- !! processed by numpydoc !! -->

#### *classmethod* from_sklearn(model)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/internals/interop.py#L222)

Create a cuml estimator from a scikit-learn estimator.

* **Parameters:**
  **model**
  : A compatible scikit-learn (or scikit-learn extension) estimator.
* **Returns:**
  cls
  : A new instance of this cuml estimator class that mirrors the
    state of the input estimator.

### Notes

`output_type` of the estimator is set to “numpy” by default, as these
cannot be inferred from training arguments. If something different is
required, then please use cuml’s output_type configuration utilities.

<!-- !! processed by numpydoc !! -->

#### get_feature_names_out(input_features=None)

Get output feature names for transformation.

The feature names out will prefixed by the lowercased class name. For
example, if the transformer outputs 3 features, then the feature names
out are: `["class_name0", "class_name1", "class_name2"]`.

* **Parameters:**
  **input_features**
  : Only used to validate feature names with the names seen in [`fit`](#cuml.decomposition.IncrementalPCA.fit).
* **Returns:**
  **feature_names_out**
  : Transformed feature names.

<!-- !! processed by numpydoc !! -->

#### get_params(deep=True)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/internals/base.py#L191)

Returns a dict of all params owned by this class. If the child class
has appropriately overridden the `_get_param_names` method and does not
need anything other than what is there in this method, then it doesn’t
have to override this method

<!-- !! processed by numpydoc !! -->

#### inverse_transform(self, X, , return_sparse=False, sparse_tol=1e-10)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/decomposition/pca.pyx#L574)

Transform data back to its original space.

In other words, return an input X_original whose transform would be X.

* **Parameters:**
  **X**
  : Dense or sparse matrix with dtype float32 or float64.
    Acceptable dense formats: CUDA array interface compliant objects like
    CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas
    DataFrame/Series.

  **return_sparse**
  : Ignored when the model is not fit on a sparse matrix
    If True, the method will convert the result to a
    cupyx.scipy.sparse.csr_matrix object.
    NOTE: Currently, there is a loss of information when converting
    to csr matrix (cusolver bug). Default will be switched to True
    once this is solved.

  **sparse_tol**
  : Ignored when return_sparse=False.
    If True, values in the inverse transform below this parameter
    are clipped to 0.
* **Returns:**
  **X_inv**
  : Transformed values
    <br/>
    For more information on how to configure cuML’s dense output type,
    refer to: [Output Data Type Configuration](../../cuml/index.html.md#output-data-type-configuration).

<!-- !! processed by numpydoc !! -->

#### partial_fit(X, y=None, , check_input=True) → [IncrementalPCA](#cuml.decomposition.IncrementalPCA)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/decomposition/incremental_pca.py#L252)

Incremental fit with X. All of X is processed as a single batch.

* **Parameters:**
  **X**
  : Training data, where n_samples is the number of samples and
    n_features is the number of features.

  **check_input**
  : Run check_array on X.

  **y**
* **Returns:**
  **self**
  : Returns the instance itself.

<!-- !! processed by numpydoc !! -->

#### set_params(\*\*params)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/internals/base.py#L200)

Accepts a dict of params and updates the corresponding ones owned by
this class. If the child class has appropriately overridden the
`_get_param_names` method and does not need anything other than what is,
there in this method, then it doesn’t have to override this method

<!-- !! processed by numpydoc !! -->

#### transform(X)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/decomposition/incremental_pca.py#L390)

Apply dimensionality reduction to X.

X is projected on the first principal components previously extracted
from a training set, using minibatches of size batch_size if X is
sparse.

* **Parameters:**
  **X**
  : New data, where n_samples is the number of samples
    and n_features is the number of features.
* **Returns:**
  **X_new**

<!-- !! processed by numpydoc !! -->