# LedoitWolf

### *class* cuml.covariance.LedoitWolf(, store_precision=True, assume_centered=False, block_size=1000, verbose=False, output_type=None)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/covariance/ledoit_wolf.py#L87)

LedoitWolf Estimator for covariance matrix estimation.

Computes the Ledoit-Wolf shrinkage estimator for the covariance matrix.
This estimator regularizes the empirical covariance by shrinking it
towards a scaled identity matrix, with the shrinkage coefficient
determined by the Ledoit-Wolf formula.

The regularized covariance is:
`(1 - shrinkage) * cov + shrinkage * mu * np.identity(n_features)`

where `mu = trace(cov) / n_features` and `shrinkage` is computed
to minimize the Mean Squared Error between the regularized estimate
and the true covariance.

* **Parameters:**
  **store_precision**
  : Specifies if the estimated precision matrix is stored.

  **assume_centered**
  : If True, data will not be centered before computation.
    Useful when working with data whose mean is almost, but not exactly
    zero. If False (default), data will be centered before computation.

  **block_size**
  : Size of blocks into which the covariance matrix will be split
    during its Ledoit-Wolf estimation. This is purely a memory
    optimization and does not affect results.

  **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:**
  **covariance_**
  : Estimated covariance matrix.

  **location_**
  : Estimated location, i.e., the estimated mean.

  **precision_**
  : Estimated pseudo inverse matrix. Only stored if `store_precision`
    is True.

  **shrinkage_**
  : Coefficient in the convex combination used for the computation
    of the shrunk estimate. Range is [0, 1].

  **n_features_in_**
  : Number of features seen during [fit](https://scikit-learn.org/stable/glossary.html#term-fit).

### Methods

| [`error_norm`](#cuml.covariance.LedoitWolf.error_norm)(comp_cov[, norm, scaling, squared])   | Compute the Mean Squared Error between two covariance estimators.   |
|---------------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| [`fit`](#cuml.covariance.LedoitWolf.fit)(X[, y])                                      | Fit the Ledoit-Wolf shrunk covariance model to X.                   |
| [`get_precision`](#cuml.covariance.LedoitWolf.get_precision)()                                  | Getter for the precision matrix.                                    |
| [`mahalanobis`](#cuml.covariance.LedoitWolf.mahalanobis)(X)                                   | Compute the squared Mahalanobis distances of given observations.    |
| [`score`](#cuml.covariance.LedoitWolf.score)(X_test[, y])                               | Compute the log-likelihood of X_test under the estimated model.     |

#### SEE ALSO
[`sklearn.covariance.LedoitWolf`](https://scikit-learn.org/stable/modules/generated/sklearn.covariance.LedoitWolf.html#sklearn.covariance.LedoitWolf)
: The scikit-learn CPU implementation.

### References

O. Ledoit and M. Wolf, “A Well-Conditioned Estimator for
Large-Dimensional Covariance Matrices”, Journal of Multivariate
Analysis, Volume 88, Issue 2, February 2004, pages 365-411.

### Examples

```pycon
>>> import cupy as cp
>>> from cuml.covariance import LedoitWolf
>>> rng = cp.random.RandomState(42)
>>> X = rng.randn(100, 5)
>>> lw = LedoitWolf().fit(X)
>>> lw.covariance_.shape
(5, 5)
>>> lw.shrinkage_
0.123...
```

<!-- !! 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 !! -->

#### error_norm(comp_cov, norm='frobenius', scaling=True, squared=True)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/covariance/ledoit_wolf.py#L337)

Compute the Mean Squared Error between two covariance estimators.

* **Parameters:**
  **comp_cov**
  : The covariance to compare with.

  **norm**
  : The type of norm used to compute the error.

  **scaling**
  : If True, the squared error is scaled by n_features.

  **squared**
  : If True, return squared error. If False, return error.
* **Returns:**
  **error**
  : The Mean Squared Error (in the sense of the Frobenius norm)
    between `self` and `comp_cov`.

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

#### fit(X, y=None) → [LedoitWolf](#cuml.covariance.LedoitWolf)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/covariance/ledoit_wolf.py#L230)

Fit the Ledoit-Wolf shrunk covariance model to X.

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

  **y**
  : Not used, present for API consistency.
* **Returns:**
  **self**
  : Returns the instance itself.

<!-- !! 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_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 !! -->

#### get_precision()[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/covariance/ledoit_wolf.py#L284)

Getter for the precision matrix.

* **Returns:**
  **precision_**
  : The precision matrix associated to the current covariance object.

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

#### mahalanobis(X)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/covariance/ledoit_wolf.py#L384)

Compute the squared Mahalanobis distances of given observations.

* **Parameters:**
  **X**
  : The observations, the Mahalanobis distances of which we compute.
* **Returns:**
  **mahalanobis_distances**
  : Squared Mahalanobis distances of the observations.

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

#### score(X_test, y=None) → [float](https://docs.python.org/3/builtins/functions.html#float)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/covariance/ledoit_wolf.py#L299)

Compute the log-likelihood of X_test under the estimated model.

The log-likelihood is computed using the Gaussian model.

* **Parameters:**
  **X_test**
  : Test data of which we compute the likelihood.

  **y**
  : Not used, present for API consistency.
* **Returns:**
  **log_likelihood**
  : Log-likelihood of the data under the fitted Gaussian model.

<!-- !! 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 !! -->