DOC Give local recommendations about IterativeImputer in docstrings (#23701)

aperezlebel · glemaitre · glemaitre · commit 67044ce028a6 · 2022-08-05T14:58:55.000+02:00
Co-authored-by: Guillaume Lemaitre &lt;g.lemaitre58@gmail.com&gt;
diff --git a/sklearn/impute/_iterative.py b/sklearn/impute/_iterative.py
@@ -183,7 +183,10 @@ class IterativeImputer(_BaseImputer):
 
     See Also
     --------
-    SimpleImputer : Univariate imputation of missing values.
+    SimpleImputer : Univariate imputer for completing missing values
+        with simple strategies.
+    KNNImputer : Multivariate imputer that estimates missing features using
+        nearest samples.
 
     Notes
     -----
@@ -194,6 +197,16 @@ class IterativeImputer(_BaseImputer):
     Features which contain all missing values at :meth:`fit` are discarded upon
     :meth:`transform`.
 
+    Using defaults, the imputer scales in :math:`\\mathcal{O}(knp^3\\min(n,p))`
+    where :math:`k` = `max_iter`, :math:`n` the number of samples and
+    :math:`p` the number of features. It thus becomes prohibitively costly when
+    the number of features increases. Setting
+    `n_nearest_features << n_features`, `skip_complete=True` or increasing `tol`
+    can help to reduce its computational cost.
+
+    Depending on the nature of missing values, simple imputers can be
+    preferable in a prediction context.
+
     References
     ----------
     .. [1] `Stef van Buuren, Karin Groothuis-Oudshoorn (2011). "mice:
diff --git a/sklearn/impute/_knn.py b/sklearn/impute/_knn.py
@@ -90,10 +90,10 @@ class KNNImputer(_BaseImputer):
 
     See Also
     --------
-    SimpleImputer : Imputation transformer for completing missing values
+    SimpleImputer : Univariate imputer for completing missing values
         with simple strategies.
-    IterativeImputer : Multivariate imputer that estimates each feature
-        from all the others.
+    IterativeImputer : Multivariate imputer that estimates values to impute for
+        each feature with missing values from all the others.
 
     References
     ----------
