API Make IterativeImputer experimental (scikit-learn#13824)

Author: jnothman

doc/conf.py

@@ -263,9 +263,9 @@
                    'sphx_glr_plot_compare_methods_001.png': 349}
 
 
-# enable experimental module so that the new GBDTs estimators can be
+# enable experimental module so that experimental estimators can be
 # discovered properly by sphinx
-from sklearn.experimental import enable_hist_gradient_boosting  # noqa
+from sklearn.experimental import *  # noqa
 
 
 def make_carousel_thumbs(app, exception):

doc/modules/classes.rst

@@ -471,6 +471,7 @@ Samples generator
    :toctree: generated/
 
    experimental.enable_hist_gradient_boosting
+   experimental.enable_iterative_imputer
 
 
 .. _feature_extraction_ref:

doc/modules/impute.rst

@@ -105,7 +105,16 @@ of ``y``.  This is done for each feature in an iterative fashion, and then is
 repeated for ``max_iter`` imputation rounds. The results of the final
 imputation round are returned.
 
+.. note::
+
+   This estimator is still **experimental** for now: the predictions
+   and the API might change without any deprecation cycle. To use it,
+   you need to explicitly import ``enable_iterative_imputer``.
+
+::
+
     >>> import numpy as np
+    >>> from sklearn.experimental import enable_iterative_imputer
     >>> from sklearn.impute import IterativeImputer
     >>> imp = IterativeImputer(max_iter=10, random_state=0)
     >>> imp.fit([[1, 2], [3, 6], [4, 8], [np.nan, 3], [7, np.nan]])  # doctest: +NORMALIZE_WHITESPACE

doc/whats_new/v0.21.rst

@@ -216,7 +216,7 @@ Support for Python 3.4 and below has been officially dropped.
 
     >>> # explicitly require this experimental feature
     >>> from sklearn.experimental import enable_hist_gradient_boosting  # noqa
-    >>> # now you can import normally from ensemble
+    >>> # now you can import normally from sklearn.ensemble
     >>> from sklearn.ensemble import HistGradientBoostingClassifier
 
   :pr:`12807` by :user:`Nicolas Hug<NicolasHug>`.
@@ -358,6 +358,15 @@ Support for Python 3.4 and below has been officially dropped.
   :pr:`12177` by :user:`Sergey Feldman <sergeyf>` and :user:`Ben Lawson
   <benlawson>`.
 
+  The API of IterativeImputer is experimental and subject to change without any
+  deprecation cycle. To use them, you need to explicitly import
+  ``enable_iterative_imputer``::
+
+    >>> from sklearn.experimental import enable_iterative_imputer  # noqa
+    >>> # now you can import normally from sklearn.impute
+    >>> from sklearn.impute import IterativeImputer
+
+
 - |Feature| The :class:`impute.SimpleImputer` and
   :class:`impute.IterativeImputer` have a new parameter ``'add_indicator'``,
   which simply stacks a :class:`impute.MissingIndicator` transform into the

examples/impute/plot_iterative_imputer_variants_comparison.py

@@ -42,6 +42,8 @@
 import matplotlib.pyplot as plt
 import pandas as pd
 
+# To use this experimental feature, we need to explicitly ask for it:
+from sklearn.experimental import enable_iterative_imputer  # noqa
 from sklearn.datasets import fetch_california_housing
 from sklearn.impute import SimpleImputer
 from sklearn.impute import IterativeImputer

examples/impute/plot_missing_values.py

@@ -23,6 +23,8 @@
 import numpy as np
 import matplotlib.pyplot as plt
 
+# To use the experimental IterativeImputer, we need to explicitly ask for it:
+from sklearn.experimental import enable_iterative_imputer  # noqa
 from sklearn.datasets import load_diabetes
 from sklearn.datasets import load_boston
 from sklearn.ensemble import RandomForestRegressor

sklearn/experimental/enable_iterative_imputer.py

@@ -0,0 +1,19 @@
+"""Enables IterativeImputer
+
+The API and results of this estimators might change without any deprecation
+cycle.
+
+Importing this file dynamically sets :class:`sklearn.impute.IterativeImputer`
+as an attribute of the impute module::
+
+    >>> # explicitly require this experimental feature
+    >>> from sklearn.experimental import enable_iterative_imputer  # noqa
+    >>> # now you can import normally from impute
+    >>> from sklearn.impute import IterativeImputer
+"""
+
+from ..impute._iterative import IterativeImputer
+from .. import impute
+
+impute.IterativeImputer = IterativeImputer
+impute.__all__ += ['IterativeImputer']

sklearn/experimental/tests/test_enable_iterative_imputer.py

@@ -0,0 +1,39 @@
+"""Tests for making sure experimental imports work as expected."""
+
+import textwrap
+
+from sklearn.utils.testing import assert_run_python_script
+
+
+def test_imports_strategies():
+    # Make sure different import strategies work or fail as expected.
+
+    # Since Python caches the imported modules, we need to run a child process
+    # for every test case. Else, the tests would not be independent
+    # (manually removing the imports from the cache (sys.modules) is not
+    # recommended and can lead to many complications).
+
+    good_import = """
+    from sklearn.experimental import enable_iterative_imputer
+    from sklearn.impute import IterativeImputer
+    """
+    assert_run_python_script(textwrap.dedent(good_import))
+
+    good_import_with_ensemble_first = """
+    import sklearn.ensemble
+    from sklearn.experimental import enable_iterative_imputer
+    from sklearn.impute import IterativeImputer
+    """
+    assert_run_python_script(textwrap.dedent(good_import_with_ensemble_first))
+
+    bad_imports = """
+    import pytest
+
+    with pytest.raises(ImportError):
+        from sklearn.impute import IterativeImputer
+
+    import sklearn.experimental
+    with pytest.raises(ImportError):
+        from sklearn.impute import IterativeImputer
+    """
+    assert_run_python_script(textwrap.dedent(bad_imports))