Add EmpiricalCovariance estimator

[csadorf]

Adds cuml.covariance.EmpiricalCovariance with sklearn-compatible fit, score, get_precision, error_norm, and mahalanobis behavior, and wires it into cuml.accel for sklearn.covariance.EmpiricalCovariance.

Includes direct estimator tests, sklearn compatibility coverage, cuml.accel integration coverage, API docs, and FAQ coverage.

Closes #7525

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[csadorf]

/ok to test d8a9b38

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: c348298a-f1e2-46bf-870d-e396adc6eac7

📥 Commits

Reviewing files that changed from the base of the PR and between d8a9b38 and 3ea5c51.

📒 Files selected for processing (2)

• docs/source/cuml-accel/faq.rst
• python/cuml/cuml/__init__.py

✅ Files skipped from review due to trivial changes (1)

• docs/source/cuml-accel/faq.rst

---

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Added EmpiricalCovariance estimator: GPU-accelerated covariance fitting, optional precision storage, log-likelihood scoring, Mahalanobis distances, and error-norm comparisons.

• Documentation

  • API docs and acceleration FAQ updated to list EmpiricalCovariance in the covariance estimation section.

• Tests

  • Comprehensive unit and integration tests added to validate behavior, sklearn compatibility, dtypes, and edge cases.

Walkthrough

This PR introduces EmpiricalCovariance, a GPU-accelerated maximum-likelihood covariance estimator for cuML with full sklearn compatibility. The implementation includes the core estimator class with fit/score/error_norm/mahalanobis methods, package exports and sklearn proxy integration, API documentation, integration tests via the accel layer, comprehensive unit tests, and test infrastructure updates.

Changes

EmpiricalCovariance GPU-Accelerated Implementation

Layer / File(s)	Summary
Core EmpiricalCovariance Implementation python/cuml/cuml/covariance/empirical_covariance.py	New EmpiricalCovariance class with _empirical_covariance and _log_likelihood helper functions. Implements fit() with optional dtype conversion and centering, get_precision() with lazy computation, score() for log-likelihood evaluation, error_norm() supporting Frobenius/spectral metrics, and mahalanobis() for distance computation. Includes sklearn CPU attribute interop via descriptors.
Package Exports and Public API Wiring python/cuml/cuml/covariance/__init__.py, python/cuml/cuml/__init__.py, python/cuml/cuml/accel/_overrides/sklearn/covariance.py	Updated cuml.covariance.__init__.py to re-export EmpiricalCovariance; exposed via top-level cuml module; created sklearn compatibility proxy in accel overrides with _gpu_class mapping.
API Documentation and FAQ docs/source/api/cuml.covariance.rst, docs/source/api/index.rst, docs/source/cuml-accel/faq.rst	Added EmpiricalCovariance to autosummary, API reference table under Covariance Estimation, and cuml-accel FAQ of accelerated sklearn estimators.
Integration Tests (sklearn.covariance proxy) python/cuml/cuml_accel_tests/integration/test_empirical_covariance.py	Parametrized tests validating store_precision attribute toggling, assume_centered centering behavior, score() finite values, mahalanobis() vector output and non-negativity, and learned attribute (covariance_, location_, precision_) existence and shapes.
Comprehensive Unit Tests (cuml.covariance) python/cuml/tests/test_empirical_covariance.py	Extensive test suite covering fit semantics, attribute shapes/symmetry/PSD, numerical parity with sklearn (covariance/location/precision/score), parameter semantics (assume_centered, store_precision), dtype preservation, multi-backend input handling (numpy/cupy/cudf/pandas), error norm metrics (Frobenius/spectral with scaling/squaring), edge cases (single-feature, single-sample, n_features > n_samples), output-type controls, sklearn interoperability (from_sklearn/as_sklearn), and parameter access.
Test Infrastructure and Compatibility python/cuml/tests/test_base.py, python/cuml/tests/test_sklearn_compatibility.py	Registered EmpiricalCovariance.score signature exception in test_base.py EXCEPTIONS; added EmpiricalCovariance() instance to test_sklearn_compatibility.py ESTIMATORS and xfail for check_estimator_tags_renamed.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Suggested labels

cuml-accel, sklearn-api-compat

Suggested reviewers

• betatim
• dantegd

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 12.28% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Add EmpiricalCovariance estimator' clearly and concisely summarizes the main change: adding a new EmpiricalCovariance estimator to the codebase.
Description check	✅ Passed	The description is related to the changeset, detailing the new EmpiricalCovariance estimator, its sklearn-compatible methods, integration with cuml.accel, and test coverage.
Linked Issues check	✅ Passed	The PR fully addresses issue #7525 by implementing sklearn-compatible EmpiricalCovariance with fit, score, get_precision, error_norm, and mahalanobis methods, integrating it into cuml.accel, and providing comprehensive test coverage.
Out of Scope Changes check	✅ Passed	All changes are within scope: implementation of EmpiricalCovariance class, public exports, cuml.accel integration, documentation updates, and comprehensive test suites directly support the linked issue #7525 objectives.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@python/cuml/cuml/__init__.py`:
- Line 25: The top-level import of EmpiricalCovariance was added but not
exported in the module's public API; update the module's __all__ list to include
"EmpiricalCovariance" so it is part of the top-level exports. Locate the __all__
variable in cuml.__init__.py (where other estimators like "LedoitWolf" are
listed) and add "EmpiricalCovariance" to that sequence, ensuring string spelling
matches the imported symbol.

In `@python/cuml/tests/test_empirical_covariance.py`:
- Around line 291-321: Add an explicit empty-input test covering n_samples=0 to
match sklearn behavior: create X = _make_random_data(n_samples=0, n_features=3)
and call EmpiricalCovariance().fit(X) and SklearnEmpiricalCovariance().fit(X);
then assert they exhibit the same outcome (either both raise the same exception
via pytest.raises(...) or both return compatible covariance_ arrays via
np.testing.assert_allclose). Reference the existing tests
(test_single_feature_matches_sklearn, test_single_sample_warns,
test_more_features_than_samples_matches_sklearn) and use the same patterns
(store_precision flag if needed) to place the new test near those edge-case
tests.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 744d464a-95e4-4c02-92a6-dabc8cd8230b

📥 Commits

Reviewing files that changed from the base of the PR and between 661a320 and d8a9b38.

📒 Files selected for processing (11)

• docs/source/api/cuml.covariance.rst
• docs/source/api/index.rst
• docs/source/cuml-accel/faq.rst
• python/cuml/cuml/__init__.py
• python/cuml/cuml/accel/_overrides/sklearn/covariance.py
• python/cuml/cuml/covariance/__init__.py
• python/cuml/cuml/covariance/empirical_covariance.py
• python/cuml/cuml_accel_tests/integration/test_empirical_covariance.py
• python/cuml/tests/test_base.py
• python/cuml/tests/test_empirical_covariance.py
• python/cuml/tests/test_sklearn_compatibility.py

[jcrist]

Nice work!

[csadorf]

/merge